docs/conf.py

   1 import os
   2 import sys
   3
   4 try:
   5     import sphinx_rtd_theme
   6 except ImportError:
   7     sphinx_rtd_theme = None
   8 try:
   9     import rst.linker as rst_linker
  10 except ImportError:
  11     rst_linker = None
  12
  13 # Add the source tree and extras/ to sys.path.
  14 srcdir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
  15 extrasdir = os.path.join(srcdir, 'extras')
  16 sys.path.insert(0, srcdir)
  17 sys.path.insert(1, extrasdir)
  18
  19 extensions = [
  20     'sphinx.ext.autodoc',
  21     'sphinx.ext.doctest',
  22     'sphinx.ext.todo',
  23     'sphinx.ext.coverage',
  24     'sphinxtogithub',
  25     # https://github.com/git-cola/git-cola/issues/1250
  26     # https://github.com/jaraco/jaraco.packaging/issues/7
  27     # 'jaraco.packaging.sphinx',
  28 ]
  29
  30 master_doc = 'index'
  31 html_theme = 'default'
  32
  33 # {package_url} is provided py jaraco.packaging.sphinx when available
  34 # for use in the rst.linker configuration. We expand the value manually for now.
  35 package_url = 'https://gitlab.com/git-cola/git-cola'
  36
  37 # Link dates and other references in the changelog
  38 if rst_linker is not None:
  39     extensions += ['rst.linker']
  40
  41 link_files = {
  42     '../CHANGES.rst': dict(
  43         using=dict(GH='https://github.com', package_url=package_url),
  44         replace=[
  45             dict(
  46                 pattern=r'(Issue #|\B#)(?P<issue>\d+)',
  47                 url='{package_url}/issues/{issue}',
  48             ),
  49             dict(
  50                 pattern=r'(?m:^((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n)',
  51                 with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
  52             ),
  53             dict(
  54                 pattern=r'PEP[- ](?P<pep_number>\d+)',
  55                 url='https://www.python.org/dev/peps/pep-{pep_number:0>4}/',
  56             ),
  57         ],
  58     )
  59 }
  60
  61 # Be strict about any broken references
  62 nitpicky = True
  63
  64 extensions += ['sphinx.ext.intersphinx']
  65 intersphinx_mapping = {
  66     'python': ('https://docs.python.org/3', None),
  67     'sphinx': ('https://www.sphinx-doc.org/en/stable/', None),
  68 }
  69
  70 # Preserve authored syntax for defaults
  71 autodoc_preserve_defaults = True
  72
  73 # Get the version from cola/_version.py.
  74 versionfile = os.path.join(srcdir, 'cola', '_version.py')
  75 scope = {}
  76 with open(versionfile) as f:
  77     exec(f.read(), scope)
  78
  79 version = scope['VERSION']  # The short X.Y version.
  80 release = version  # The full version, including alpha/beta/rc tags.
  81
  82 authors = 'David Aguilar and contributors'
  83 man_pages = [
  84     ('git-cola', 'git-cola', 'The highly caffeinated Git GUI', authors, '1'),
  85     ('git-dag', 'git-dag', 'The sleek and powerful Git history browser', authors, '1'),
  86 ]
  87
  88 # Sphinx 4.0 creates sub-directories for each man section.
  89 # Disable this feature for consistency across Sphinx versions.
  90 man_make_section_directory = False
  91
  92 # Enable the sphinx_rtd_theme.
  93 if sphinx_rtd_theme is not None:
  94     extensions += ['sphinx_rtd_theme']
  95     html_theme = 'sphinx_rtd_theme'