Moving configuration to sphinx.toml file (#14427)

This is a PR to move all _static_ docs configuration from the conf.py
file to a toml file.

I did things in the simplest way possible since I figure it's no use
trying to optimize this now.

docs/source/sphinx.toml

@@ -0,0 +1,70 b''
+title = "Sphinx configuration"
+
+[sphinx]
+templates_path = ["_templates"]
+master_doc = "index"
+project = "IPython"
+copyright = "The IPython Development Team"
+github_project_url = "https://github.com/ipython/ipython"
+source_suffix = ".rst"
+exclude_patterns = ["**.ipynb_checkpoints"]
+pygments_style = "sphinx"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.graphviz",
+    "sphinxcontrib.jquery",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
+    "sphinx.ext.napoleon",  # to preprocess docstrings
+    "github",  # for easy GitHub links
+    "magics",
+    "configtraits",
+]
+default_role = "literal"
+modindex_common_prefix = ["IPython."]
+
+[intersphinx_mapping]
+python = { url = 'https://docs.python.org/3/', fallback = '' }
+rpy2 = { url = 'https://rpy2.github.io/doc/latest/html/', fallback = '' }
+jupyterclient = { url = 'https://jupyter-client.readthedocs.io/en/latest/', fallback = '' }
+jupyter = { url = 'https://jupyter.readthedocs.io/en/latest/', fallback = '' }
+jedi = { url = 'https://jedi.readthedocs.io/en/latest/', fallback = '' }
+traitlets = { url = 'https://traitlets.readthedocs.io/en/latest/', fallback = '' }
+ipykernel = { url = 'https://ipykernel.readthedocs.io/en/latest/', fallback = '' }
+prompt_toolkit = { url = 'https://python-prompt-toolkit.readthedocs.io/en/stable/', fallback = '' }
+ipywidgets = { url = 'https://ipywidgets.readthedocs.io/en/stable/', fallback = '' }
+ipyparallel = { url = 'https://ipyparallel.readthedocs.io/en/stable/', fallback = '' }
+pip = { url = 'https://pip.pypa.io/en/stable/', fallback = '' }
+
+[html]
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_favicon = "_static/favicon.ico"
+html_last_updated_fmt = "%b %d, %Y"
+htmlhelp_basename = "ipythondoc"
+html_additional_pages = [
+    ["interactive/htmlnotebook", "notebook_redirect.html"],
+    ["interactive/notebook", "notebook_redirect.html"],
+    ["interactive/nbconvert", "notebook_redirect.html"],
+    ["interactive/public_server", "notebook_redirect.html"]
+]
+
+[numpydoc]
+numpydoc_show_class_members = "False"
+numpydoc_class_members_toctree = "False"
+warning_is_error = "True"
+
+[latex]
+latex_documents = [
+    ['index', 'ipython.tex', 'IPython Documentation',
+     'The IPython Development Team', 'manual', 'True'],
+    ['parallel/winhpc_index', 'winhpc_whitepaper.tex',
+     'Using IPython on Windows HPC Server 2008',
+     "Brian E. Granger", 'manual', 'True']
+]
+latex_use_modindex = "True"
+latex_font_size = "11pt"

docs/source/conf.py

@@ -15,14 +15,23 b''
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
+
 import sys, os
 from pathlib import Path
 
+if sys.version_info > (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+with open("./sphinx.toml", "rb") as f:
+    config = tomllib.load(f)
+
 # https://read-the-docs.readthedocs.io/en/latest/faq.html
-ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
+ON_RTD = os.environ.get("READTHEDOCS", None) == "True"
 
 if ON_RTD:
-    tags.add('rtd')
+    tags.add("rtd")
 
     # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
     for name in ("config", "api", "magics", "shortcuts"):
@@ -38,9 +47,6 b' if ON_RTD:'
             )
 import sphinx_rtd_theme
 
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
 # Allow Python scripts to change behaviour during sphinx run
 os.environ["IN_SPHINX_RUN"] = "True"
 
@@ -52,7 +58,7 b' autodoc_type_aliases = {'
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../sphinxext'))
+sys.path.insert(0, os.path.abspath("../sphinxext"))
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
@@ -68,44 +74,120 b' exec('
 # General configuration
 # ---------------------
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.doctest",
-    "sphinx.ext.inheritance_diagram",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.graphviz",
-    "sphinxcontrib.jquery",
-    "IPython.sphinxext.ipython_console_highlighting",
-    "IPython.sphinxext.ipython_directive",
-    "sphinx.ext.napoleon",  # to preprocess docstrings
-    "github",  # for easy GitHub links
-    "magics",
-    "configtraits",
+# - template_path: Add any paths that contain templates here, relative to this directory.
+# - master_doc: The master toctree document.
+# - project
+# - copyright
+# - github_project_url
+# - source_suffix = config["sphinx"]["source_suffix"]
+# - exclude_patterns:
+#       Exclude these glob-style patterns when looking for source files.
+#       They are relative to the source/ directory.
+# - pygments_style: The name of the Pygments (syntax highlighting) style to use.
+# - extensions:
+#        Add any Sphinx extension module names here, as strings. They can be extensions
+#        coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# - default_role
+# - modindex_common_prefix
+
+locals().update(config["sphinx"])
+
+intersphinx_mapping = config["intersphinx_mapping"]
+for k, v in intersphinx_mapping.items():
+    intersphinx_mapping[k] = tuple(
+        [intersphinx_mapping[k]["url"], intersphinx_mapping[k]["fallback"]]
+    )
+
+# numpydoc config
+numpydoc_show_class_members = config["numpydoc"][
+    "numpydoc_show_class_members"
+]  # Otherwise Sphinx emits thousands of warnings
+numpydoc_class_members_toctree = config["numpydoc"]["numpydoc_class_members_toctree"]
+warning_is_error = config["numpydoc"]["warning_is_error"]
+
+# Options for HTML output
+# -----------------------
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# - html_theme
+# - html_static_path
+#     Add any paths that contain custom static files (such as style sheets) here,
+#     relative to this directory. They are copied after the builtin static files,
+#     so a file named "default.css" will overwrite the builtin "default.css".
+#     Favicon needs the directory name
+# - html_favicon
+# - html_last_updated_fmt = config["html"]["html_last_updated_fmt"]
+#     If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+#     using the given strftime format.
+#     Output file base name for HTML help builder.
+# - htmlhelp_basename
+locals().update(config["html"])
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+html_additional_pages = {}
+for item in config["html"]["html_additional_pages"]:
+    html_additional_pages[item[0]] = item[1]
+
+# Options for LaTeX output
+# ------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = []
+for item in config["latex"]["latex_documents"]:
+    latex_documents.append(tuple(item))
+# If false, no module index is generated.
+latex_use_modindex = config["latex"]["latex_use_modindex"]
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = config["latex"]["latex_font_size"]
+
+# Options for texinfo output
+# --------------------------
+texinfo_documents = [
+    (
+        master_doc,
+        "ipython",
+        "IPython Documentation",
+        "The IPython Development Team",
+        "IPython",
+        "IPython Documentation",
+        "Programming",
+        1,
+    ),
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+#########################################################################
+# Custom configuration
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The full version, including alpha/beta/rc tags.
+release = "%s" % iprelease["version"]
+# Just the X.Y.Z part, no '-dev'
+version = iprelease["version"].split("-", 1)[0]
 
-# The suffix of source filenames.
-source_suffix = '.rst'
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = "%B %d, %Y"
+
+rst_prolog = ""
 
-rst_prolog = ''
 
 def is_stable(extra):
-    for ext in {'dev', 'b', 'rc'}:
+    for ext in {"dev", "b", "rc"}:
         if ext in extra:
             return False
     return True
 
-if is_stable(iprelease['_version_extra']):
-    tags.add('ipystable')
-    print('Adding Tag: ipystable')
+
+if is_stable(iprelease["_version_extra"]):
+    tags.add("ipystable")
+    print("Adding Tag: ipystable")
 else:
-    tags.add('ipydev')
-    print('Adding Tag: ipydev')
+    tags.add("ipydev")
+    print("Adding Tag: ipydev")
     rst_prolog += """
 .. warning::
 
@@ -126,23 +208,9 b' rst_prolog += """'
 
 """
 
-# The master toctree document.
-master_doc = 'index'
-
-# General substitutions.
-project = 'IPython'
-copyright = 'The IPython Development Team'
-
-# ghissue config
-github_project_url = "https://github.com/ipython/ipython"
-
-# numpydoc config
-numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
-numpydoc_class_members_toctree = False
-warning_is_error = True
-
 import logging
 
+
 class ConfigtraitFilter(logging.Filter):
     """
     This is a filter to remove in sphinx 3+ the error about config traits being duplicated.
@@ -153,178 +221,22 b' class ConfigtraitFilter(logging.Filter):'
     """
 
     def filter(self, record):
-        if record.args and record.args[0] == 'configtrait' and 'duplicate' in record.msg:
+        if (
+            record.args
+            and record.args[0] == "configtrait"
+            and "duplicate" in record.msg
+        ):
             return False
         return True
 
+
 ct_filter = ConfigtraitFilter()
 
 import sphinx.util
-logger = sphinx.util.logging.getLogger('sphinx.domains.std').logger
 
+logger = sphinx.util.logging.getLogger("sphinx.domains.std").logger
 logger.addFilter(ct_filter)
 
-# The default replacements for |version| and |release|, also used in various
-# other places throughout the built documents.
-#
-# The full version, including alpha/beta/rc tags.
-release = "%s" % iprelease['version']
-# Just the X.Y.Z part, no '-dev'
-version = iprelease['version'].split('-', 1)[0]
-
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# Exclude these glob-style patterns when looking for source files. They are
-# relative to the source/ directory.
-exclude_patterns = ["**.ipynb_checkpoints"]
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# Set the default role so we can use `foo` instead of ``foo``
-default_role = 'literal'
-
-# Options for HTML output
-# -----------------------
-
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-# html_style = 'default.css'
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# The name of an image file (within the static path) to place at the top of
-# the sidebar.
-#html_logo = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# Favicon needs the directory name
-html_favicon = '_static/favicon.ico'
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-html_additional_pages = {
-    'interactive/htmlnotebook': 'notebook_redirect.html',
-    'interactive/notebook': 'notebook_redirect.html',
-    'interactive/nbconvert': 'notebook_redirect.html',
-    'interactive/public_server': 'notebook_redirect.html',
-}
-
-# If false, no module index is generated.
-#html_use_modindex = True
-
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'ipythondoc'
-
-intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
-                       'rpy2': ('https://rpy2.github.io/doc/latest/html/', None),
-                       'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
-                       'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
-                       'jedi': ('https://jedi.readthedocs.io/en/latest/', None),
-                       'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
-                       'ipykernel': ('https://ipykernel.readthedocs.io/en/latest/', None),
-                       'prompt_toolkit' : ('https://python-prompt-toolkit.readthedocs.io/en/stable/', None),
-                       'ipywidgets': ('https://ipywidgets.readthedocs.io/en/stable/', None),
-                       'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None),
-                       'pip': ('https://pip.pypa.io/en/stable/', None)
-                      }
-
-# Options for LaTeX output
-# ------------------------
-
-# The font size ('10pt', '11pt' or '12pt').
-latex_font_size = '11pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
-
-latex_documents = [
-    ('index', 'ipython.tex', 'IPython Documentation',
-     u"""The IPython Development Team""", 'manual', True),
-    ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
-     'Using IPython on Windows HPC Server 2008',
-     u"Brian E. Granger", 'manual', True)
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-latex_use_modindex = True
-
-
-# Options for texinfo output
-# --------------------------
-
-texinfo_documents = [
-  (master_doc, 'ipython', 'IPython Documentation',
-   'The IPython Development Team',
-   'IPython',
-   'IPython Documentation',
-   'Programming',
-   1),
-]
-
-modindex_common_prefix = ['IPython.']
-
 
 def setup(app):
     app.add_css_file("theme_overrides.css")

pyproject.toml

@@ -61,17 +61,18 b' black = ['
     "black",
 ]
 doc = [
+    "docrepr",
+    "exceptiongroup",
     "ipykernel",
+    "ipython[test]",
+    "matplotlib",
     "setuptools>=18.5",
-    "sphinx>=1.3",
     "sphinx-rtd-theme",
+    "sphinx>=1.3",
     "sphinxcontrib-jquery",
-    "docrepr",
-    "matplotlib",
     "stack_data",
+    "tomli ; python_version<'3.11'",
     "typing_extensions",
-    "exceptiongroup",
-    "ipython[test]",
 ]
 kernel = [
     "ipykernel",