conf.py
273 lines
| 8.2 KiB
| text/x-python
|
PythonLexer
|
r1116 | # -*- coding: utf-8 -*- | ||
# | ||||
|
r1695 | # IPython documentation build configuration file. | ||
|
r1539 | |||
# NOTE: This file has been edited manually from the auto-generated one from | ||||
# sphinx. Do NOT delete and re-generate. If any changes from sphinx are | ||||
# needed, generate a scratch one and merge by hand any new fields needed. | ||||
|
r1116 | # | ||
# This file is execfile()d with the current directory set to its containing dir. | ||||
# | ||||
# The contents of this file are pickled, so don't put values in the namespace | ||||
# that aren't pickleable (module imports are okay, they're removed automatically). | ||||
# | ||||
# All configuration values have a default value; values that are commented out | ||||
# serve to show the default value. | ||||
|
r28771 | |||
|
r1256 | import sys, os | ||
|
r26146 | from pathlib import Path | ||
|
r1116 | |||
|
r28771 | if sys.version_info > (3, 11): | ||
import tomllib | ||||
else: | ||||
import tomli as tomllib | ||||
with open("./sphinx.toml", "rb") as f: | ||||
config = tomllib.load(f) | ||||
|
r28769 | |||
|
r26565 | # https://read-the-docs.readthedocs.io/en/latest/faq.html | ||
|
r28770 | ON_RTD = os.environ.get("READTHEDOCS", None) == "True" | ||
|
r8151 | |||
if ON_RTD: | ||||
|
r28770 | tags.add("rtd") | ||
|
r21589 | |||
# RTD doesn't use the Makefile, so re-run autogen_{things}.py here. | ||||
|
r26148 | for name in ("config", "api", "magics", "shortcuts"): | ||
fname = Path("autogen_{}.py".format(name)) | ||||
fpath = (Path(__file__).parent).joinpath("..", fname) | ||||
|
r27495 | with open(fpath, encoding="utf-8") as f: | ||
exec( | ||||
compile(f.read(), fname, "exec"), | ||||
{ | ||||
"__file__": fpath, | ||||
"__name__": "__main__", | ||||
}, | ||||
) | ||||
|
r28383 | import sphinx_rtd_theme | ||
|
r27778 | # Allow Python scripts to change behaviour during sphinx run | ||
os.environ["IN_SPHINX_RUN"] = "True" | ||||
autodoc_type_aliases = { | ||||
"Matcher": " IPython.core.completer.Matcher", | ||||
"MatcherAPIv1": " IPython.core.completer.MatcherAPIv1", | ||||
} | ||||
|
r1256 | # 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. | ||||
|
r28770 | sys.path.insert(0, os.path.abspath("../sphinxext")) | ||
|
r1695 | |||
|
r1539 | # We load the ipython release info into a dict by explicit execution | ||
iprelease = {} | ||||
|
r27495 | exec( | ||
compile( | ||||
open("../../IPython/core/release.py", encoding="utf-8").read(), | ||||
"../../IPython/core/release.py", | ||||
"exec", | ||||
), | ||||
iprelease, | ||||
) | ||||
|
r1539 | |||
|
r1116 | # General configuration | ||
# --------------------- | ||||
|
r28771 | # - 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"]) | ||||
|
r28769 | |||
|
r28773 | try: | ||
from intersphinx_registry import get_intersphinx_mapping | ||||
intersphinx_mapping = get_intersphinx_mapping( | ||||
packages={ | ||||
"python", | ||||
"rpy2", | ||||
"jupyterclient", | ||||
"jupyter", | ||||
"jedi", | ||||
"traitlets", | ||||
"ipykernel", | ||||
"prompt_toolkit", | ||||
"ipywidgets", | ||||
"ipyparallel", | ||||
"pip", | ||||
} | ||||
|
r28769 | ) | ||
|
r28773 | except ModuleNotFoundError: | ||
# In case intersphinx_registry is not yet packages on current plaform | ||||
# as it is quite recent. | ||||
print("/!\\ intersphinx_registry not installed, relying on local mapping.") | ||||
intersphinx_mapping = config["intersphinx_mapping"] | ||||
for k, v in intersphinx_mapping.items(): | ||||
intersphinx_mapping[k] = tuple( | ||||
[intersphinx_mapping[k]["url"], intersphinx_mapping[k]["fallback"]] | ||||
) | ||||
|
r28769 | # 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()] | ||||
|
r28771 | # - 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"]) | ||||
|
r28769 | |||
# 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, | ||||
), | ||||
|
r2275 | ] | ||
|
r1116 | |||
|
r28769 | ######################################################################### | ||
# 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. | ||||
|
r28770 | release = "%s" % iprelease["version"] | ||
|
r28769 | # Just the X.Y.Z part, no '-dev' | ||
|
r28770 | version = iprelease["version"].split("-", 1)[0] | ||
|
r1116 | |||
|
r28769 | # There are two options for replacing |today|: either, you set today to some | ||
# non-false value, then it is used: | ||||
|
r28770 | # today = '' | ||
|
r28769 | # Else, today_fmt is used as the format for a strftime call. | ||
|
r28770 | today_fmt = "%B %d, %Y" | ||
|
r1116 | |||
|
r28769 | rst_prolog = "" | ||
|
r22829 | |||
|
r28770 | |||
|
r22589 | def is_stable(extra): | ||
|
r28770 | for ext in {"dev", "b", "rc"}: | ||
|
r22589 | if ext in extra: | ||
return False | ||||
return True | ||||
|
r28770 | |||
if is_stable(iprelease["_version_extra"]): | ||||
tags.add("ipystable") | ||||
print("Adding Tag: ipystable") | ||||
|
r22589 | else: | ||
|
r28770 | tags.add("ipydev") | ||
print("Adding Tag: ipydev") | ||||
|
r22829 | rst_prolog += """ | ||
.. warning:: | ||||
|
r22845 | This documentation covers a development version of IPython. The development | ||
version may differ significantly from the latest stable release. | ||||
|
r22829 | """ | ||
rst_prolog += """ | ||||
.. important:: | ||||
|
r11812 | |||
|
r22845 | This documentation covers IPython versions 6.0 and higher. Beginning with | ||
version 6.0, IPython stopped supporting compatibility with Python versions | ||||
lower than 3.3 including all versions of Python 2.7. | ||||
If you are looking for an IPython version compatible with Python 2.7, | ||||
please use the IPython 5.x LTS release and refer to its documentation (LTS | ||||
is the long term support release). | ||||
|
r11812 | |||
|
r22829 | """ | ||
|
r11812 | |||
|
r25609 | import logging | ||
|
r28770 | |||
|
r25609 | class ConfigtraitFilter(logging.Filter): | ||
""" | ||||
|
r26030 | This is a filter to remove in sphinx 3+ the error about config traits being duplicated. | ||
|
r25609 | |||
As we autogenerate configuration traits from, subclasses have lots of | ||||
duplication and we want to silence them. Indeed we build on travis with | ||||
warnings-as-error set to True, so those duplicate items make the build fail. | ||||
""" | ||||
def filter(self, record): | ||||
|
r28770 | if ( | ||
record.args | ||||
and record.args[0] == "configtrait" | ||||
and "duplicate" in record.msg | ||||
): | ||||
|
r25609 | return False | ||
return True | ||||
|
r28770 | |||
|
r25609 | ct_filter = ConfigtraitFilter() | ||
import sphinx.util | ||||
|
r28770 | |||
logger = sphinx.util.logging.getLogger("sphinx.domains.std").logger | ||||
|
r25609 | logger.addFilter(ct_filter) | ||
|
r10009 | |||
|
r28010 | def setup(app): | ||
app.add_css_file("theme_overrides.css") | ||||
|
r1695 | # Cleanup | ||
# ------- | ||||
# delete release info to avoid pickling errors from sphinx | ||||
|
r1539 | del iprelease | ||