Experimental: moving configuration to sphinx.toml file

This is a draft PR to move all static configuration from the conf.py
file to a toml file.

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,9 +15,12 b''
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
+import toml
 import sys, os
 from pathlib import Path
 
+config = toml.load("./sphinx.toml")
+
 # https://read-the-docs.readthedocs.io/en/latest/faq.html
 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
 
@@ -38,9 +41,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"
 
@@ -68,31 +68,113 b' exec('
 # General configuration
 # ---------------------
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = config["sphinx"]["templates_path"]
+# The master toctree document.
+master_doc = config["sphinx"]["master_doc"]
+# General substitutions.
+project = config["sphinx"]["project"]
+copyright = config["sphinx"]["copyright"]
+# ghissue config
+github_project_url = config["sphinx"]["github_project_url"]
+# The suffix of source filenames.
+source_suffix = config["sphinx"]["source_suffix"]
+# Exclude these glob-style patterns when looking for source files. They are
+# relative to the source/ directory.
+exclude_patterns = config["sphinx"]["exclude_patterns"]
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = config["sphinx"]["pygments_style"]
 # 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",
+extensions = config["sphinx"]["extensions"]
+# Set the default role so we can use `foo` instead of ``foo``
+default_role = config["sphinx"]["default_role"]
+modindex_common_prefix = config["sphinx"]["modindex_common_prefix"]
+
+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 = config["html"]["html_theme"]
+html_theme_path = [sphinx_rtd_theme.get_html_theme_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".
+html_static_path = config["html"]["html_static_path"]
+# Favicon needs the directory name
+html_favicon = config["html"]["html_favicon"]
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = config["html"]["html_last_updated_fmt"]
+# Output file base name for HTML help builder.
+htmlhelp_basename = config["html"]["htmlhelp_basename"]
+
+# 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'}:
@@ -126,21 +208,6 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):
@@ -161,170 +228,8 b' ct_filter = ConfigtraitFilter()'
 
 import sphinx.util
 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

@@ -72,6 +72,7 b' doc = ['
     "typing_extensions",
     "exceptiongroup",
     "ipython[test]",
+    "toml",
 ]
 kernel = [
     "ipykernel",