Skip to content

Commit

Permalink
Add lightweight comments to conf.py and update docs readme (GH-126100)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
3 people authored Oct 29, 2024
1 parent aab58a9 commit 9effa0f
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 14 deletions.
7 changes: 2 additions & 5 deletions Doc/README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_.
23 changes: 14 additions & 9 deletions Doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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',
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.
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

0 comments on commit 9effa0f

Please sign in to comment.