doc/conf.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # GHC Users Guide documentation build configuration file
   4 #
   5 # This file is execfile()d with the current directory set to its
   6 # containing dir.
   7 #
   8 import sys
   9 import os
  10 import sphinx_rtd_theme
  11
  12 # Support for :base-ref:, etc.
  13 sys.path.insert(0, os.path.abspath('.'))
  14 import cabaldomain
  15
  16 version = "3.11.0.0"
  17
  18 extensions = [
  19     'sphinx.ext.extlinks',
  20     'sphinx.ext.todo',
  21     'sphinx-jsonschema',
  22     'sphinxnotes.strike'
  23 ]
  24
  25 templates_path = ['_templates']
  26 source_suffix = '.rst'
  27 source_encoding = 'utf-8-sig'
  28 root_doc = 'index'
  29
  30 # extlinks -- see http://www.sphinx-doc.org/en/stable/ext/extlinks.html
  31 extlinks = {
  32     'issue': ('https://github.com/haskell/cabal/issues/%s', 'issue #%s'),
  33
  34     'ghc-wiki': ('https://gitlab.haskell.org/ghc/ghc/-/wikis/%s', '%s'),
  35     'ghc-ticket': ('https://gitlab.haskell.org/ghc/ghc/-/issues/%s', 'GHC issue #%s'),
  36
  37     'hackage-pkg': ('http://hackage.haskell.org/package/%s', '%s'),
  38 }
  39
  40 # General information about the project.
  41 project = u'Cabal'
  42 copyright = u'2003-2023, Cabal Team'
  43 # N.B. version comes from ghc_config
  44 release = version  # The full version, including alpha/beta/rc tags.
  45
  46 # Syntax highlighting
  47 highlight_language = 'cabal'
  48 #pygments_style = 'tango'
  49
  50 primary_domain = 'cabal'
  51
  52 # List of patterns, relative to source directory, that match files and
  53 # directories to ignore when looking for source files.
  54 exclude_patterns = ['.build', "*.gen.rst"]
  55
  56 # -- Options for HTML output ---------------------------------------------
  57
  58 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
  59 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
  60
  61 html_theme = 'sphinx_rtd_theme'
  62 # only import the theme if we're building docs locally
  63 if on_rtd:
  64     html_style = None
  65     using_rtd_theme = True
  66 else:
  67     import sphinx_rtd_theme
  68     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  69
  70 # The name for this set of Sphinx documents.  If None, it defaults to
  71 # "<project> v<release> documentation".
  72 html_title = "Cabal {} User's Guide".format(release)
  73 html_short_title = "Cabal %s User's Guide" % release
  74 html_logo = 'images/Cabal-dark.png'
  75 html_static_path = ['images']
  76 # Convert quotes and dashes to typographically correct entities
  77 html_use_smartypants = True
  78 html_show_copyright = True
  79 html_context = {
  80     'source_url_prefix': "https://github.com/haskell/cabal/tree/master/doc/",
  81     "display_github": True,
  82     "github_host": "github.com",
  83     "github_user": "haskell",
  84     "github_repo": 'cabal',
  85     "github_version": "master/",
  86     "conf_py_path": "doc/",
  87     "source_suffix": '.rst',
  88 }
  89 html_theme_options = {
  90     'collapse_navigation': False,
  91 }
  92
  93
  94 # If true, an OpenSearch description file will be output, and all pages will
  95 # contain a <link> tag referring to it.  The value of this option must be the
  96 # base URL from which the finished HTML is served.
  97 html_use_opensearch = 'https://cabal.readthedocs.io/en/stable'
  98
  99 # This is the file name suffix for HTML files (e.g. ".xhtml").
 100 #html_file_suffix = None
 101
 102 # Output file base name for HTML help builder.
 103 htmlhelp_basename = 'CabalUsersGuide'
 104
 105 # MathJax to use HTML rendering by default (makes the text selectable, see #8453)
 106 mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS_CHTML'
 107
 108
 109 # -- Options for LaTeX output ---------------------------------------------
 110
 111 latex_elements = {
 112     'inputenc': '',
 113     'utf8extra': '',
 114     'preamble': r'''
 115 \usepackage{fontspec}
 116 \usepackage{makeidx}
 117 \setsansfont{DejaVu Sans}
 118 \setromanfont{DejaVu Serif}
 119 \setmonofont{DejaVu Sans Mono}
 120 ''',
 121 }
 122
 123 # Grouping the document tree into LaTeX files. List of tuples
 124 # (source start file, target name, title,
 125 #  author, documentclass [howto, manual, or own class]).
 126 latex_documents = [
 127   ('index', 'users_guide.tex', u'GHC Users Guide Documentation',
 128    u'GHC Team', 'manual'),
 129 ]
 130
 131 # The name of an image file (relative to this directory) to place at the top of
 132 # the title page.
 133 #latex_logo = 'images/logo.pdf'
 134 latex_logo = 'images/Cabal-dark.png'
 135
 136 # If true, show page references after internal links.
 137 latex_show_pagerefs = True
 138
 139 # http://www.sphinx-doc.org/en/master/usage/extensions/todo.html
 140 todo_include_todos = True
 141
 142 # -- Options for manual page output ---------------------------------------
 143
 144 # One entry per manual page. List of tuples
 145 # (source start file, name, description, authors, manual section).
 146 man_pages = [
 147     ('cabal', 'cabal', 'The Haskell Cabal', 'The Cabal Team', 1)
 148 ]
 149
 150 # If true, show URL addresses after external links.
 151 #man_show_urls = False
 152
 153
 154 # -- Options for Texinfo output -------------------------------------------
 155
 156 # Grouping the document tree into Texinfo files. List of tuples
 157 # (source start file, target name, title, author,
 158 #  dir menu entry, description, category)
 159 texinfo_documents = [
 160   ('index', 'CabalUsersGuide', u'Cabal Users Guide',
 161    u'Cabal Team', 'CabalUsersGuide', 'The Haskell Cabal.',
 162    'Compilers'),
 163 ]
 164
 165 from sphinx import addnodes
 166 from docutils import nodes
 167
 168 def parse_ghci_cmd(env, sig, signode):
 169     name = sig.split(';')[0]
 170     sig = sig.replace(';', '')
 171     signode += addnodes.desc_name(name, sig)
 172     return name
 173
 174 def parse_flag(env, sig, signode):
 175     import re
 176     names = []
 177     for i, flag in enumerate(sig.split(',')):
 178         flag = flag.strip()
 179         sep = '='
 180         parts = flag.split('=')
 181         if len(parts) == 1:
 182             sep=' '
 183             parts = flag.split()
 184         if len(parts) == 0: continue
 185
 186         name = parts[0]
 187         names.append(name)
 188         sig = sep + ' '.join(parts[1:])
 189         sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
 190         if i > 0:
 191             signode += addnodes.desc_name(', ', ', ')
 192         signode += addnodes.desc_name(name, name)
 193         if len(sig) > 0:
 194             signode += addnodes.desc_addname(sig, sig)
 195
 196     return names[0]
 197
 198 def setup(app):
 199     from sphinx.util.docfields import Field, TypedField
 200
 201     increase_python_stack()
 202
 203     # the :ghci-cmd: directive used in ghci.rst
 204     app.add_object_type('ghci-cmd', 'ghci-cmd',
 205                         parse_node=parse_ghci_cmd,
 206                         objname='GHCi command',
 207                         indextemplate='pair: %s; GHCi command')
 208
 209     app.add_object_type('ghc-flag', 'ghc-flag',
 210                         objname='GHC command-line option',
 211                         parse_node=parse_flag,
 212                         indextemplate='pair: %s; GHC option',
 213                         doc_field_types=[
 214                             Field('since', label='Introduced in GHC version', names=['since']),
 215                             Field('default', label='Default value', names=['default']),
 216                             Field('static')
 217                         ])
 218
 219     app.add_object_type('rts-flag', 'rts-flag',
 220                         objname='runtime system command-line option',
 221                         parse_node=parse_flag,
 222                         indextemplate='pair: %s; RTS option',
 223                         doc_field_types=[
 224                             Field('since', label='Introduced in GHC version', names=['since']),
 225                         ])
 226
 227     cabaldomain.setup(app)
 228
 229 def increase_python_stack():
 230     # Workaround sphinx-build recursion limit overflow:
 231     # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
 232     #  RuntimeError: maximum recursion depth exceeded while pickling an object
 233     #
 234     # Default python allows recursion depth of 1000 calls.
 235     sys.setrecursionlimit(10000)