[3.12] Add lightweight comments to conf.py and update docs readme (GH-126100) (#126135)

Add lightweight comments to conf.py and update docs readme (GH-126100)

* Update contributing contact info in readme

* Add lightweight comments to improve docs workflow understanding

* Apply code review suggestions from @hugovk

* Add code review suggestion from @AA-Turner

* Update Doc/conf.py

* Update Doc/conf.py

* Update Doc/conf.py

---------

(cherry picked from commit 9effa0ff06047f3d957bf37267742a98106581ff)

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

diff --git a/Doc/README.rst b/Doc/README.rst
index efcee0db428908a50533ad7ca2f6e7b2efbb1c51..2d1148753e0c6bbd7ca4f0f659a62012b8471e24 100644 (file)
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -133,8 +133,5 @@ Bugs in the content should be reported to the
 
 Bugs in the toolset should be reported to the tools themselves.
 
-You can also send a mail to the Python Documentation Team at docs@python.org,
-and we will process your request as soon as possible.
-
-If you want to help the Documentation Team, you are always welcome.  Just send
-a mail to docs@python.org.
+To help with the documentation, or report any problems, please leave a message
+on `discuss.python.org <https://discuss.python.org/c/documentation>`_.

diff --git a/Doc/conf.py b/Doc/conf.py
index f4cf4ee9547e192957b02dfbb1a7b1ade6b816a9..938a61347bac3f5826f0e0dd2cdfd1716bf4a17f 100644 (file)
--- 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',
@@ -48,7 +51,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
@@ -72,10 +75,10 @@ rst_epilog = f"""
 .. |python_version_literal| replace:: ``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.
@@ -87,10 +90,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')
@@ -307,8 +311,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,
@@ -354,7 +359,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.
@@ -600,8 +605,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'