Adding upstream version 7.3.7.upstream/7.3.7

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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]
+    )