diff options
Diffstat (limited to 'Doc/conf.py')
| -rw-r--r-- | Doc/conf.py | 23 |
1 files changed, 14 insertions, 9 deletions
diff --git a/Doc/conf.py b/Doc/conf.py index 7ee3c91..5e65d52 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -13,14 +13,17 @@ import time import sphinx +# Make our custom extensions available to Sphinx sys.path.append(os.path.abspath('tools/extensions')) sys.path.append(os.path.abspath('includes')) +# Python specific content from Doc/Tools/extensions/pyspecific.py from pyspecific import SOURCE_URI # General configuration # --------------------- +# Our custom Sphinx extensions are found in Doc/Tools/extensions/ extensions = [ 'audit_events', 'availability', @@ -54,7 +57,7 @@ try: except ImportError: _tkinter = None # Treat warnings as errors, done here to prevent warnings in Sphinx code from -# causing spurious test failures. +# causing spurious CPython test failures. import warnings warnings.simplefilter('error') del warnings @@ -80,10 +83,10 @@ rst_epilog = f""" .. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}`` """ -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: +# There are two options for replacing |today|. Either, you set today to some +# non-false value and use it. today = '' -# Else, today_fmt is used as the format for a strftime call. +# Or else, today_fmt is used as the format for a strftime call. today_fmt = '%B %d, %Y' # By default, highlight as Python 3. @@ -95,10 +98,11 @@ needs_sphinx = '7.2.6' # Create table of contents entries for domain objects (e.g. functions, classes, # attributes, etc.). Default is True. toc_object_entries = True +# Hide parents to tidy up long entries in sidebar toc_object_entries_show_parents = 'hide' # Ignore any .rst files in the includes/ directory; -# they're embedded in pages but not rendered individually. +# they're embedded in pages but not rendered as individual pages. # Ignore any .rst files in the venv/ directory. exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst'] venvdir = os.getenv('VENVDIR') @@ -329,8 +333,9 @@ gettext_additional_targets = [ # Options for HTML output # ----------------------- -# Use our custom theme. +# Use our custom theme: https://github.com/python/python-docs-theme html_theme = 'python_docs_theme' +# Location of overrides for theme templates and static files html_theme_path = ['tools'] html_theme_options = { 'collapsiblesidebar': True, @@ -376,7 +381,7 @@ else: html_last_updated_fmt, time.gmtime(html_time) ) -# Path to find HTML templates. +# Path to find HTML templates to override theme templates_path = ['tools/templates'] # Custom sidebar templates, filenames relative to this file. @@ -621,8 +626,8 @@ if sphinx.version_info[:2] < (8, 1): "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"), } -# Options for c_annotations -# ------------------------- +# Options for c_annotations extension +# ----------------------------------- # Relative filename of the data files refcount_file = 'data/refcounts.dat' |