diff options
Diffstat (limited to 'doc/conf.py')
| -rw-r--r-- | doc/conf.py | 156 |
1 files changed, 102 insertions, 54 deletions
diff --git a/doc/conf.py b/doc/conf.py index d4915aa..49fcba4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -8,11 +8,17 @@ import sphinx os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.autosummary', 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.coverage'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.autosummary', + 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.coverage', +] coverage_statistics_to_report = coverage_statistics_to_stdout = True templates_path = ['_templates'] exclude_patterns = ['_build'] @@ -22,6 +28,8 @@ copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers' version = sphinx.__display_version__ release = version show_authors = True +nitpicky = True +show_warning_types = True html_theme = 'sphinx13' html_theme_path = ['_themes'] @@ -47,73 +55,107 @@ epub_uid = 'web-site' epub_scheme = 'url' epub_identifier = epub_publisher epub_pre_files = [('index.xhtml', 'Welcome')] -epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'), - ('develop.xhtml', 'Sphinx development')] -epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', - '_static/searchtools.js', - '_static/sphinx_highlight.js', - '_static/basic.css', - '_static/language_data.js', - 'search.html', '_static/websupport.js'] +epub_post_files = [ + ('usage/installation.xhtml', 'Installing Sphinx'), + ('develop.xhtml', 'Sphinx development'), +] +epub_exclude_files = [ + '_static/opensearch.xml', + '_static/doctools.js', + '_static/searchtools.js', + '_static/sphinx_highlight.js', + '_static/basic.css', + '_static/language_data.js', + 'search.html', + '_static/websupport.js', +] epub_fix_images = False epub_max_image_width = 0 epub_show_urls = 'inline' epub_use_index = False epub_description = 'Sphinx documentation generator system manual' -latex_documents = [('index', 'sphinx.tex', 'Sphinx Documentation', - 'the Sphinx developers', 'manual', 1)] +latex_documents = [ + ('index', 'sphinx.tex', 'Sphinx Documentation', 'the Sphinx developers', 'manual', 1) +] latex_logo = '_static/sphinx.png' latex_elements = { 'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}', - 'passoptionstopackages': r''' + 'passoptionstopackages': r""" \PassOptionsToPackage{svgnames}{xcolor} -''', - 'preamble': r''' +""", + 'preamble': r""" \DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}} \setcounter{tocdepth}{3}% depth of what main TOC shows (3=subsubsection) \setcounter{secnumdepth}{1}% depth of section numbering \setlength{\tymin}{2cm}% avoid too cramped table columns -''', +""", # fix missing index entry due to RTD doing only once pdflatex after makeindex - 'printindex': r''' + 'printindex': r""" \IfFileExists{\jobname.ind} {\footnotesize\raggedright\printindex} {\begin{sphinxtheindex}\end{sphinxtheindex}} -''', +""", } latex_show_urls = 'footnote' latex_use_xindy = True linkcheck_timeout = 5 +linkcheck_ignore = [ + r'^contents\.html$', # extra generated page + r'^\.\./contents\.html$', + re.escape('https://gitlab.com/projects/new'), # requires sign-in + re.escape('https://web.libera.chat/?channel=#sphinx-doc'), +] +linkcheck_anchors_ignore_for_url = [ + # anchors in Markdown files cannot be accessed directly + 'https://github.com/Khan/style-guides/blob/master/style/python.md', +] autodoc_member_order = 'groupwise' autosummary_generate = False todo_include_todos = True -extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/' - 'restructuredtext.html#%s', '%s'), - 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/' - 'roles.html#%s', '%s'), - 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/' - 'directives.html#%s', '%s')} +extlinks = { + 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/' '%s.html', '%s'), + 'duref': ( + 'https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s', + '%s', + ), + 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/' 'roles.html#%s', '%s'), + 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/' 'directives.html#%s', '%s'), +} man_pages = [ - ('index', 'sphinx-all', 'Sphinx documentation generator system manual', - 'the Sphinx developers', 1), - ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool', - '', 1), - ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation ' - 'template generator', '', 1), - ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool', - '', 1), - ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages', - '', 1), + ( + 'index', + 'sphinx-all', + 'Sphinx documentation generator system manual', + 'the Sphinx developers', + 1, + ), + ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool', '', 1), + ( + 'man/sphinx-quickstart', + 'sphinx-quickstart', + 'Sphinx documentation ' 'template generator', + '', + 1, + ), + ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool', '', 1), + ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages', '', 1), ] texinfo_documents = [ - ('index', 'sphinx', 'Sphinx Documentation', 'the Sphinx developers', - 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools', - 1), + ( + 'index', + 'sphinx', + 'Sphinx Documentation', + 'the Sphinx developers', + 'Sphinx', + 'The Sphinx documentation builder.', + 'Documentation tools', + 1, + ), ] intersphinx_mapping = { @@ -127,7 +169,10 @@ locale_dirs = ['locale/'] gettext_compact = False nitpick_ignore = { - ('cpp:class', 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner'), # NoQA: E501 + ( + 'cpp:class', + 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner', + ), # NoQA: E501 ('cpp:identifier', 'MyContainer'), ('js:func', 'SomeError'), ('js:func', 'number'), @@ -188,7 +233,7 @@ nitpick_ignore = { # -- Extension interface ------------------------------------------------------- -from sphinx import addnodes # noqa: E402 +from sphinx import addnodes # NoQA: E402 event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') @@ -209,16 +254,15 @@ def parse_event(env, sig, signode): def linkify_issues_in_changelog(app, docname, source): - """ Linkify issue references like #123 in changelog to GitHub. """ - + """Linkify issue references like #123 in changelog to GitHub.""" if docname == 'changes': - changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES") + changelog_path = os.path.join(os.path.dirname(__file__), '../CHANGES.rst') # this path trickery is needed because this script can # be invoked with different working directories: # * running make in docs/ # * running tox -e docs in the repo root dir - with open(changelog_path, encoding="utf-8") as f: + with open(changelog_path, encoding='utf-8') as f: changelog = f.read() def linkify(match): @@ -227,18 +271,22 @@ def linkify_issues_in_changelog(app, docname, source): linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog) - source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog) + source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog) def setup(app): from sphinx.ext.autodoc import cut_lines from sphinx.util.docfields import GroupedField + app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) app.connect('source-read', linkify_issues_in_changelog) - app.add_object_type('confval', 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value') - fdesc = GroupedField('parameter', label='Parameters', - names=['param'], can_collapse=True) - app.add_object_type('event', 'event', 'pair: %s; event', parse_event, - doc_field_types=[fdesc]) + app.add_object_type( + 'confval', + 'confval', + objname='configuration value', + indextemplate='pair: %s; configuration value', + ) + fdesc = GroupedField('parameter', label='Parameters', names=['param'], can_collapse=True) + app.add_object_type( + 'event', 'event', 'pair: %s; event', parse_event, doc_field_types=[fdesc] + ) |