diff options
Diffstat (limited to 'doc/conf.py')
| -rw-r--r-- | doc/conf.py | 105 |
1 files changed, 72 insertions, 33 deletions
diff --git a/doc/conf.py b/doc/conf.py index 49fcba4..9582f79 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,10 +1,11 @@ # Sphinx documentation build configuration file +from __future__ import annotations import os import re import time -import sphinx +from sphinx import __display_version__ os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -18,6 +19,7 @@ extensions = [ 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.coverage', + 'sphinx.ext.graphviz', ] coverage_statistics_to_report = coverage_statistics_to_stdout = True templates_path = ['_templates'] @@ -25,8 +27,7 @@ exclude_patterns = ['_build'] project = 'Sphinx' copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers' -version = sphinx.__display_version__ -release = version +release = version = __display_version__ show_authors = True nitpicky = True show_warning_types = True @@ -114,15 +115,15 @@ linkcheck_anchors_ignore_for_url = [ autodoc_member_order = 'groupwise' autosummary_generate = False -todo_include_todos = True +todo_include_todos = 'READTHEDOCS' not in os.environ extlinks = { - 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/' '%s.html', '%s'), + 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/%s.html', '%s'), 'duref': ( - 'https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s', + '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'), + '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 = [ @@ -137,7 +138,7 @@ man_pages = [ ( 'man/sphinx-quickstart', 'sphinx-quickstart', - 'Sphinx documentation ' 'template generator', + 'Sphinx documentation template generator', '', 1, ), @@ -154,7 +155,7 @@ texinfo_documents = [ 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools', - 1, + True, ), ] @@ -179,11 +180,16 @@ nitpick_ignore = { ('js:func', 'string'), ('py:attr', 'srcline'), ('py:class', 'Element'), # sphinx.domains.Domain + ('py:class', 'Documenter'), # sphinx.application.Sphinx.add_autodocumenter ('py:class', 'IndexEntry'), # sphinx.domains.IndexEntry ('py:class', 'Node'), # sphinx.domains.Domain ('py:class', 'NullTranslations'), # gettext.NullTranslations ('py:class', 'RoleFunction'), # sphinx.domains.Domain + ('py:class', 'RSTState'), # sphinx.utils.parsing.nested_parse_to_nodes ('py:class', 'Theme'), # sphinx.application.TemplateBridge + ('py:class', 'SearchLanguage'), # sphinx.application.Sphinx.add_search_language + ('py:class', 'StringList'), # sphinx.utils.parsing.nested_parse_to_nodes + ('py:class', 'system_message'), # sphinx.utils.docutils.SphinxDirective ('py:class', 'TitleGetter'), # sphinx.domains.Domain ('py:class', 'XRefRole'), # sphinx.domains.Domain ('py:class', 'docutils.nodes.Element'), @@ -234,13 +240,14 @@ nitpick_ignore = { # -- Extension interface ------------------------------------------------------- from sphinx import addnodes # NoQA: E402 +from sphinx.application import Sphinx # NoQA: E402, TCH001 -event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') +_event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') def parse_event(env, sig, signode): - m = event_sig_re.match(sig) - if not m: + m = _event_sig_re.match(sig) + if m is None: signode += addnodes.desc_name(sig, sig) return sig name, args = m.groups() @@ -253,40 +260,72 @@ def parse_event(env, sig, signode): return name -def linkify_issues_in_changelog(app, docname, source): +def linkify_issues_in_changelog(app, path, docname, source): """Linkify issue references like #123 in changelog to GitHub.""" if docname == '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: - changelog = f.read() def linkify(match): url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1] return f'`{match[0]} <{url}>`_' - linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog) + linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, source[0]) + + source[0] = linkified_changelog + - source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog) +REDIRECT_TEMPLATE = """ +<html> + <head> + <noscript> + <meta http-equiv="refresh" content="0; url={{rel_url}}"/> + </noscript> + </head> + <body> + <script> + window.location.href = '{{rel_url}}' + (window.location.search || '') + (window.location.hash || ''); + </script> + <p>You should have been redirected.</p> + <a href="{{rel_url}}">If not, click here to continue.</a> + </body> +</html> +""" # noqa: E501 -def setup(app): +def build_redirects(app: Sphinx, exception: Exception | None) -> None: + # this is a very simple implementation of + # https://github.com/wpilibsuite/sphinxext-rediraffe/blob/main/sphinxext/rediraffe.py + # to re-direct some old pages to new ones + if exception is not None or app.builder.name != 'html': + return + for page, rel_redirect in ( + (('development', 'overview.html'), 'index.html'), + (('development', 'builders.html'), 'howtos/builders.html'), + (('development', 'theming.html'), 'html_themes/index.html'), + (('development', 'templating.html'), 'html_themes/templating.html'), + (('development', 'tutorials', 'helloworld.html'), 'extending_syntax.html'), + (('development', 'tutorials', 'todo.html'), 'extending_build.html'), + (('development', 'tutorials', 'recipe.html'), 'adding_domain.html'), + ): + path = app.outdir.joinpath(*page) + if path.exists(): + continue + path.parent.mkdir(parents=True, exist_ok=True) + with path.open('w', encoding='utf-8') as f: + f.write(REDIRECT_TEMPLATE.replace('{{rel_url}}', rel_redirect)) + + +def setup(app: Sphinx) -> None: 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', - ) + app.connect('include-read', linkify_issues_in_changelog) + app.connect('build-finished', build_redirects) 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] + 'event', + 'event', + 'pair: %s; event', + parse_event, + doc_field_types=[fdesc], ) |