use black pre-commit

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+default_install_hook_types: [pre-commit]
+
+repos:
+  - repo: "https://github.com/psf/black"
+    rev: "22.3.0"
+    hooks:
+      - id: black
+        stages: [commit]

doc/conf.py

@@ -6,127 +6,166 @@
 
 import sphinx
 
-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']
+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",
+]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build']
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
 
-project = 'Sphinx'
+project = "Sphinx"
 copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
 version = sphinx.__display_version__
 release = version
 show_authors = True
 
-html_theme = 'sphinx13'
-html_theme_path = ['_themes']
+html_theme = "sphinx13"
+html_theme_path = ["_themes"]
 html_css_files = [
     # 'basic.css',  # included through inheritance from the basic theme
-    'sphinx13.css',
+    "sphinx13.css",
 ]
-modindex_common_prefix = ['sphinx.']
-html_static_path = ['_static']
-html_title = 'Sphinx documentation'
-html_additional_pages = {'contents': 'contents.html'}
-html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
-html_baseurl = 'https://www.sphinx-doc.org/en/master/'
-html_favicon = '_static/favicon.svg'
-
-htmlhelp_basename = 'Sphinxdoc'
-
-epub_theme = 'epub'
-epub_basename = 'sphinx'
-epub_author = 'the Sphinx developers'
-epub_publisher = 'https://www.sphinx-doc.org/'
-epub_uid = 'web-site'
-epub_scheme = 'url'
+modindex_common_prefix = ["sphinx."]
+html_static_path = ["_static"]
+html_title = "Sphinx documentation"
+html_additional_pages = {"contents": "contents.html"}
+html_use_opensearch = "https://www.sphinx-doc.org/en/master"
+html_baseurl = "https://www.sphinx-doc.org/en/master/"
+html_favicon = "_static/favicon.svg"
+
+htmlhelp_basename = "Sphinxdoc"
+
+epub_theme = "epub"
+epub_basename = "sphinx"
+epub_author = "the Sphinx developers"
+epub_publisher = "https://www.sphinx-doc.org/"
+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_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_fix_images = False
 epub_max_image_width = 0
-epub_show_urls = 'inline'
+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_logo = '_static/sphinx.png'
+epub_description = "Sphinx documentation generator system manual"
+
+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'''
+    "fontenc": r"\usepackage[LGR,X2,T1]{fontenc}",
+    "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_show_urls = "footnote"
 latex_use_xindy = True
 
-autodoc_member_order = 'groupwise'
+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 = {
+    "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 = {
-    'python': ('https://docs.python.org/3/', None),
-    'requests': ('https://requests.readthedocs.io/en/latest/', None),
-    'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
+    "python": ("https://docs.python.org/3/", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+    "readthedocs": ("https://docs.readthedocs.io/en/stable", None),
 }
 
 # Sphinx document translation with sphinx gettext feature uses these settings:
-locale_dirs = ['locale/']
+locale_dirs = ["locale/"]
 gettext_compact = False
 
 
 # -- Extension interface -------------------------------------------------------
 
 from sphinx import addnodes  # noqa: E402
 
-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):
@@ -137,17 +176,17 @@ def parse_event(env, sig, signode):
     name, args = m.groups()
     signode += addnodes.desc_name(name, name)
     plist = addnodes.desc_parameterlist()
-    for arg in args.split(','):
+    for arg in args.split(","):
         arg = arg.strip()
         plist += addnodes.desc_parameter(arg, arg)
     signode += plist
     return name
 
 
 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':
+    if docname == "changes":
         changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
         # this path trickery is needed because this script can
         # be invoked with different working directories:
@@ -158,41 +197,52 @@ def linkify_issues_in_changelog(app, docname, source):
             changelog = f.read()
 
         def linkify(match):
-            url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
-            return f'`{match[0]} <{url}>`_'
+            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, changelog)
 
-        source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
+        source[0] = source[0].replace(".. include:: ../CHANGES", 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')
-    app.add_object_type('setuptools-confval', 'setuptools-confval',
-                        objname='setuptools configuration value',
-                        indextemplate='pair: %s; setuptools 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.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.add_object_type(
+        "setuptools-confval",
+        "setuptools-confval",
+        objname="setuptools configuration value",
+        indextemplate="pair: %s; setuptools 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]
+    )
 
     # Load jQuery and patches to make readthedocs-doc-embed.js available (refs: #10574)
-    app.add_js_file('https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js',
-                    priority=100)
     app.add_js_file(
-        'https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.13.1/underscore-min.js',
+        "https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js", priority=100
+    )
+    app.add_js_file(
+        "https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.13.1/underscore-min.js",
         priority=100,
     )
-    app.add_js_file('_sphinx_javascript_frameworks_compat.js', priority=105)
+    app.add_js_file("_sphinx_javascript_frameworks_compat.js", priority=105)
 
     # workaround for RTD
     from sphinx.util import logging
+
     logger = logging.getLogger(__name__)
     app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
     app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)