From aa60681602e22c60310aadfb2d34f75e56ed1697 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 28 Oct 2024 17:23:27 -0700 Subject: [PATCH 1/7] Update contributing contact info in readme --- Doc/README.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/README.rst b/Doc/README.rst index efcee0db428908..27a9708c7d5e6f 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -133,8 +133,6 @@ 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. +If you want to help the Documentation Team, you are always welcome. +Leave a message on +`discuss.python.org `_. From 6794884e9f7d9161ad28920163f6f995621d9cd3 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 28 Oct 2024 18:04:13 -0700 Subject: [PATCH 2/7] Add lightweight comments to improve docs workflow understanding --- Doc/conf.py | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 7ee3c91581345d..41fe9b8533c80a 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -13,14 +13,17 @@ import sphinx +# Set path to cpython's doc extensions sys.path.append(os.path.abspath('tools/extensions')) sys.path.append(os.path.abspath('includes')) +# Python specific content from `Doc/Tools/extensions` from pyspecific import SOURCE_URI # General configuration # --------------------- +# Add CPython doc extensions `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' From c6aeb6a4c24c6e05b3e9f26c27ea7fdd9192754c Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 29 Oct 2024 09:52:47 -0700 Subject: [PATCH 3/7] Apply code review suggestions from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/conf.py b/Doc/conf.py index 41fe9b8533c80a..0299bb0818a431 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -13,7 +13,7 @@ import sphinx -# Set path to cpython's doc extensions +# Set path to CPython's doc extensions sys.path.append(os.path.abspath('tools/extensions')) sys.path.append(os.path.abspath('includes')) From c0dec733de9ff96e872a3bfc8263fe05711f8144 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 29 Oct 2024 10:14:46 -0700 Subject: [PATCH 4/7] Add code review suggestion from @AA-Turner Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/README.rst b/Doc/README.rst index 27a9708c7d5e6f..2d1148753e0c6b 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -133,6 +133,5 @@ Bugs in the content should be reported to the Bugs in the toolset should be reported to the tools themselves. -If you want to help the Documentation Team, you are always welcome. -Leave a message on -`discuss.python.org `_. +To help with the documentation, or report any problems, please leave a message +on `discuss.python.org `_. From ccec6800b11509cd95962c49df972e4c3e656476 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 29 Oct 2024 10:15:29 -0700 Subject: [PATCH 5/7] Update Doc/conf.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/conf.py b/Doc/conf.py index 0299bb0818a431..5fbc3de871cdb3 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -23,7 +23,7 @@ # General configuration # --------------------- -# Add CPython doc extensions `Doc/Tools/extensions` +# Our custom Sphinx extensions are found in Doc/Tools/extensions/ extensions = [ 'audit_events', 'availability', From 916b464aaf1cff1078167d6dafb48811681ab0d0 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 29 Oct 2024 10:15:38 -0700 Subject: [PATCH 6/7] Update Doc/conf.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/conf.py b/Doc/conf.py index 5fbc3de871cdb3..ff76b769ed9565 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -17,7 +17,7 @@ sys.path.append(os.path.abspath('tools/extensions')) sys.path.append(os.path.abspath('includes')) -# Python specific content from `Doc/Tools/extensions` +# Python specific content from Doc/Tools/extensions/pyspecific.py from pyspecific import SOURCE_URI # General configuration From 4db67fb8f9ba48063c4e3170109c3ed94b657fe7 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 29 Oct 2024 10:15:51 -0700 Subject: [PATCH 7/7] Update Doc/conf.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/conf.py b/Doc/conf.py index ff76b769ed9565..5e65d52f3c08c1 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -13,7 +13,7 @@ import sphinx -# Set path to CPython's doc extensions +# Make our custom extensions available to Sphinx sys.path.append(os.path.abspath('tools/extensions')) sys.path.append(os.path.abspath('includes'))