Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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 <1324225+hugovk@users.noreply.github.com>

* Add code review suggestion from @AA-Turner

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

* Update Doc/conf.py

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

* Update Doc/conf.py

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

* Update Doc/conf.py

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.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>
This commit is contained in:
Carol Willing 2024-10-29 10:45:03 -07:00 committed by GitHub
parent aab58a93ef
commit 9effa0ff06
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 16 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
Doc/README.rst
View File

@ -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>`_.

23
Doc/conf.py
View File

@ -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'