mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-22 17:55:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 15

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

Browse source 
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 9effa0ff06)

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>
This commit is contained in:
Miss Islington (bot) 2024-10-29 20:22:38 +01:00 • committed by GitHub
parent 515a5d3498
commit db0a1b8c12
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 16 additions and 14 deletions
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',
@ -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'