summaryrefslogtreecommitdiffstats
path: root/doc/conf.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/conf.py156
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]
+ )