From 5de84c9242643f786eff03726286578726d7d390 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 5 Jun 2024 18:20:59 +0200 Subject: Merging upstream version 7.3.7. Signed-off-by: Daniel Baumann --- doc/usage/extensions/autodoc.rst | 2 +- doc/usage/extensions/coverage.rst | 6 +++--- doc/usage/extensions/example_google.py | 1 + doc/usage/extensions/example_numpy.py | 6 +++--- doc/usage/extensions/graphviz.rst | 2 +- doc/usage/extensions/intersphinx.rst | 1 + doc/usage/extensions/math.rst | 4 ++-- doc/usage/extensions/napoleon.rst | 8 ++++---- 8 files changed, 16 insertions(+), 14 deletions(-) (limited to 'doc/usage/extensions') diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 1498ae9..c920de8 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -40,7 +40,7 @@ you can also enable the :mod:`napoleon ` extension. :mod:`napoleon ` is a preprocessor that converts your docstrings to correct reStructuredText before :mod:`autodoc` processes them. -.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings +.. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index 1390ebf..b9c493b 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -9,7 +9,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`. .. class:: CoverageBuilder To use this builder, activate the coverage extension in your configuration - file and give ``-b coverage`` on the command line. + file and give ``-M coverage`` on the command line. .. todo:: Write this section. @@ -62,7 +62,7 @@ should check: .. confval:: coverage_statistics_to_report - Print a tabluar report of the coverage statistics to the coverage report. + Print a tabular report of the coverage statistics to the coverage report. ``True`` by default. Example output: @@ -81,7 +81,7 @@ should check: .. confval:: coverage_statistics_to_stdout - Print a tabluar report of the coverage statistics to standard output. + Print a tabular report of the coverage statistics to standard output. ``False`` by default. Example output: diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py index 434fa3b..7cd24d1 100644 --- a/doc/usage/extensions/example_google.py +++ b/doc/usage/extensions/example_google.py @@ -290,6 +290,7 @@ class ExampleClass: def _private_without_docstring(self): pass + class ExamplePEP526Class: """The summary line for a class docstring should fit on one line. diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py index 2346b1e..d258ca3 100644 --- a/doc/usage/extensions/example_numpy.py +++ b/doc/usage/extensions/example_numpy.py @@ -266,7 +266,7 @@ class ExampleClass: self.attr3 = param3 #: Doc comment *inline* with attribute #: list(str): Doc comment *before* attribute, with type specified - self.attr4 = ["attr4"] + self.attr4 = ['attr4'] self.attr5 = None """str: Docstring *after* attribute, with type specified.""" @@ -274,7 +274,7 @@ class ExampleClass: @property def readonly_property(self): """str: Properties should be documented in their getter method.""" - return "readonly_property" + return 'readonly_property' @property def readwrite_property(self): @@ -284,7 +284,7 @@ class ExampleClass: If the setter method contains notable behavior, it should be mentioned here. """ - return ["readwrite_property"] + return ['readwrite_property'] @readwrite_property.setter def readwrite_property(self, value): diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index c134f6d..231bd36 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -211,7 +211,7 @@ There are also these config values: :program:`sphinx-build` command line via the :option:`-D ` option should be preferable, like this:: - sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html + sphinx-build -M html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build .. confval:: graphviz_dot_args diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index 5aaaf9f..e81719f 100644 --- a/doc/usage/extensions/intersphinx.rst +++ b/doc/usage/extensions/intersphinx.rst @@ -218,6 +218,7 @@ The Intersphinx extension provides the following role. e.g., ``:external:py:class:`zipfile.ZipFile```, or - ``:external:reftype:`target```, e.g., ``:external:doc:`installation```. + With this shorthand, the domain is assumed to be ``std``. If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in :confval:`intersphinx_mapping`, diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index df4fc6b..251d721 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -75,7 +75,7 @@ are built: :program:`sphinx-build` command line via the :option:`-D ` option should be preferable, like this:: - sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html + sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build This value should only contain the path to the latex executable, not further arguments; use :confval:`imgmath_latex_args` for that purpose. @@ -316,5 +316,5 @@ package jsMath_. It provides this config value: .. _dvisvgm: https://dvisvgm.de/ .. _dvisvgm FAQ: https://dvisvgm.de/FAQ .. _MathJax: https://www.mathjax.org/ -.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/ +.. _jsMath: https://www.math.union.edu/~dpvc/jsmath/ .. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst index d2391da..4b077de 100644 --- a/doc/usage/extensions/napoleon.rst +++ b/doc/usage/extensions/napoleon.rst @@ -63,14 +63,14 @@ Getting Started ~~~~~~~~~~~~~~~ 1. After :doc:`setting up Sphinx ` to build your docs, - enable napoleon in the Sphinx `conf.py` file:: + enable napoleon in the Sphinx ``conf.py`` file:: # conf.py # Add napoleon to the extensions list extensions = ['sphinx.ext.napoleon'] -2. Use `sphinx-apidoc` to build your API documentation:: +2. Use ``sphinx-apidoc`` to build your API documentation:: $ sphinx-apidoc -f -o docs/source projectdir @@ -271,8 +271,8 @@ Configuration ------------- Listed below are all the settings used by napoleon and their default -values. These settings can be changed in the Sphinx `conf.py` file. Make -sure that "sphinx.ext.napoleon" is enabled in `conf.py`:: +values. These settings can be changed in the Sphinx ``conf.py`` file. Make +sure that "sphinx.ext.napoleon" is enabled in ``conf.py``:: # conf.py -- cgit v1.2.3