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
   9 # Add the cola source directory to sys.path
  10 docdir = os.path.abspath(os.path.realpath(__file__))
  11 srcdir = os.path.dirname(os.path.dirname(docdir))
  12 extrasdir = os.path.join(srcdir, 'extras')
  13 sys.path.insert(1, extrasdir)
  14
  15 extensions = [
  16     'sphinx.ext.autodoc',
  17     'sphinx.ext.doctest',
  18     'sphinx.ext.todo',
  19     'sphinx.ext.coverage',
  20     'sphinxtogithub',
  21     # https://github.com/git-cola/git-cola/issues/1250
  22     # https://github.com/jaraco/jaraco.packaging/issues/7
  23     # 'jaraco.packaging.sphinx',
  24     # Python 3.11 https://github.com/git-cola/git-cola/issues/1251
  25     #'rst.linker',
  26 ]
  27 if sphinx_rtd_theme:
  28     extensions.append('sphinx_rtd_theme')
  29
  30 templates_path = ['_templates']
  31 source_suffix = '.rst'
  32 source_encoding = 'utf-8'
  33 master_doc = 'index'
  34
  35 project = 'git-cola'
  36 copyright = '2007-2022, David Aguilar and contributors'
  37 authors = 'David Aguilar and contributors'
  38
  39 versionfile = os.path.join(srcdir, 'cola', '_version.py')
  40 scope = {}
  41 with open(versionfile) as f:
  42     exec(f.read(), scope)
  43
  44 # The short X.Y version.
  45 version = scope['VERSION']
  46 # The full version, including alpha/beta/rc tags.
  47 release = version
  48
  49 exclude_trees = ['_build']
  50 add_function_parentheses = True
  51 pygments_style = 'default'
  52
  53 if sphinx_rtd_theme:
  54     html_theme = 'sphinx_rtd_theme'
  55 html_theme_path = ['_themes']
  56 html_static_path = ['_static']
  57 html_show_sourcelink = True
  58 htmlhelp_basename = 'git-cola-doc'
  59
  60 man_pages = [
  61     ('git-cola', 'git-cola', 'The highly caffeinated Git GUI', authors, '1'),
  62     ('git-dag', 'git-dag', 'The sleek and powerful Git history browser', authors, '1'),
  63 ]
  64
  65 # Sphinx 4.0 creates sub-directories for each man section.
  66 # Disable this feature for consistency across Sphinx versions.
  67 man_make_section_directory = False
  68
  69 latex_documents = [
  70     (
  71         'index',
  72         'git-cola.tex',
  73         'git-cola Documentation',
  74         'David Aguilar and contributors',
  75         'manual',
  76     ),
  77 ]
  78
  79 # Example configuration for intersphinx: refer to the Python standard library.
  80 intersphinx_mapping = {'https://docs.python.org/3': None}
  81
  82 # {package_url} is provided py jaraco.packaging.sphinx when available
  83 # for use in the rst.linker configuration. We expand the value manually for now.
  84 package_url = 'https://github.com/git-cola/git-cola'
  85
  86 link_files = {
  87     '../CHANGES.rst': dict(
  88         using=dict(GH='https://github.com'),
  89         replace=[
  90             dict(
  91                 pattern=r'(Issue #|\B#)(?P<issue>\d+)',
  92                 url='%s/issues/{issue}' % package_url,
  93             ),
  94             dict(
  95                 pattern=r'\B\+(?P<pull>\d+)',
  96                 url='%s/pull/{pull}' % package_url,
  97             ),
  98             dict(
  99                 pattern=r'^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n',
 100                 with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
 101             ),
 102             dict(
 103                 pattern=r'PEP[- ](?P<pep_number>\d+)',
 104                 url='https://www.python.org/dev/peps/pep-{pep_number:0>4}/',
 105             ),
 106         ],
 107     )
 108 }