Skip to content

Add lightweight comments to conf.py and update docs readme #126100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 29, 2024
Merged

Add lightweight comments to conf.py and update docs readme #126100

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
aa60681
Update contributing contact info in readme
willingc Oct 29, 2024
6794884
Add lightweight comments to improve docs workflow understanding
willingc Oct 29, 2024
c6aeb6a
Apply code review suggestions from @hugovk
willingc Oct 29, 2024
c0dec73
Add code review suggestion from @AA-Turner
willingc Oct 29, 2024
ccec680
Update Doc/conf.py
willingc Oct 29, 2024
916b464
Update Doc/conf.py
willingc Oct 29, 2024
4db67fb
Update Doc/conf.py
willingc Oct 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 3 additions & 5 deletions Doc/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 [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].
If you want to help the Documentation Team, you are always welcome.
Leave a message on
`discuss.python.org <https://discuss.python.org/c/documentation>`_.
23 changes: 14 additions & 9 deletions Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second change is wrong, the previous text was correct: if you (editor of conf.py) set the variable to a non-falce value, then it will be used (by sphinx when generating pages)

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.
Expand All @@ -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')
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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'
Expand Down
Loading