docs/conf.py

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