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

Co-authored-by: Hugo van Kemenade <[email protected]>

* Add code review suggestion from @AA-Turner

Co-authored-by: Adam Turner <[email protected]>

* Update Doc/conf.py

Co-authored-by: Adam Turner <[email protected]>

* Update Doc/conf.py

Co-authored-by: Adam Turner <[email protected]>

* Update Doc/conf.py

Co-authored-by: Adam Turner <[email protected]>

---------

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

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 [email protected],
-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 [email protected].
+To help with the documentation, or report any problems, please leave a message
+on `discuss.python.org <https://discuss.python.org/c/documentation>`_.

Doc/conf.py

@@ -13,14 +13,17 @@
 
 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 @@
 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 @@
 .. |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 @@
 # 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 @@
 # 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 @@
         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 @@
         "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'