From abd7a699e69055e938332771ceb391e4f312eac1 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Fri, 1 Aug 2025 18:37:21 +0200 Subject: [PATCH 1/5] Fix some small things --- .../all_in_one_restructuredtext.py | 30 ++++++++++++------- sample-docs/kitchen-sink/api.rst | 11 ++++++- 2 files changed, 29 insertions(+), 12 deletions(-) diff --git a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py index c310a1bcdf..2056723196 100644 --- a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py +++ b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py @@ -5,23 +5,30 @@ """ # TODO: -# - show roles to refer to elements -# - async with -# - async for -# - add example of numpy-style docstrings +# - show the roles to refer to the listed directives +# - missing: async with, async for +# - add example(s) of numpy-style docstrings import abc from typing import TypeAlias, TypeVar, final -ParameterT = TypeVar("ParameterT") #: Docstring of type ParameterT +ParameterT = TypeVar("ParameterT") #: Docstring of type :py:type:`ParameterT` ReturnT = TypeVar("ReturnT") -"""Docstring of type ReturnT.""" +"""Docstring of type :any:`ReturnT`.""" -# Python 3.12: type MyType = list[float] #: The docstring. -MyType: TypeAlias = list[float] #: The docstring. +# type MyType = list[ +# float +# ] #: The docstring of :py:type:`MyType` using Python 3.12 syntax. -my_module_level_variable: MyType = [0.0, 1.1] #: The docstring. +MyType: TypeAlias = list[ + float +] #: The docstring of :py:type:`MyType` using an explicit ``TypeAlias``. + +my_module_level_variable: MyType = [ + 0.0, + 1.1, +] #: The docstring of :py:data:`my_module_level_variable`. def my_function_pure_sphinx(*args, **kwargs): @@ -106,7 +113,8 @@ def my_function2(foo: int, bar: str): None .. deprecated:: 2.0 - Use :func:`my_function_pure_sphinx` instead. + (This is an example of a deprecation admonition.) + Use :py:func:`my_function_pure_sphinx` instead. Text at end of docstring. """ @@ -131,7 +139,7 @@ class MyException(Exception): class AllInOne: """This is a class that demonstrates various Python features. - Uses Google-style docstrings + It uses Google-style docstrings (https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html). Attributes: diff --git a/sample-docs/kitchen-sink/api.rst b/sample-docs/kitchen-sink/api.rst index 4acc24b0cf..d4cad5fb98 100644 --- a/sample-docs/kitchen-sink/api.rst +++ b/sample-docs/kitchen-sink/api.rst @@ -7,6 +7,13 @@ API documentation ***************** + A domain is a collection of markup (directives and roles) to describe and link to objects belonging together, + e.g. elements of a programming language. + + -- https://www.sphinx-doc.org/en/master/usage/domains/index.html + +The following sections show examples of the domains built-in to Sphinx. + .. toctree:: :titlesonly: :glob: @@ -38,7 +45,9 @@ Using Sphinx's :any:`sphinx.ext.autodoc` plugin, it is possible to auto-generate The ``automodule`` Directive with reStructuredText Markup --------------------------------------------------------- -What follows is an example showing usage of the ``.. automodule::`` directive. +What follows after the line is an example showing usage of the ``.. automodule::`` directive. + +--- .. currentmodule:: all_in_one_restructuredtext From 8e169461798679947e0c0f46a6940599f316e81f Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Sun, 3 Aug 2025 13:04:36 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Steve Piercy --- .../all_in_one_restructuredtext.py | 10 ++++--- sample-docs/kitchen-sink/api.rst | 27 ++++++++++++++----- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py index 2056723196..29f17a230e 100644 --- a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py +++ b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py @@ -112,7 +112,7 @@ def my_function2(foo: int, bar: str): Returns: None - .. deprecated:: 2.0 + .. deprecated:: x.y (This is an example of a deprecation admonition.) Use :py:func:`my_function_pure_sphinx` instead. @@ -168,9 +168,11 @@ def my_method( Args: my_param: Documenting *my_param*. - Another sentence on the next docstring line, still belonging to *my_param*. + This is another sentence on the next docstring line, + still belonging to *my_param*. keyword_only_param: Documenting *keyword_only_param*. - Another sentence on the next docstring line, still belonging to *keyword_only_param*. + This is another sentence on the next docstring line, + still belonging to *keyword_only_param*. Returns: The value of the local variable ``my_var``. @@ -188,7 +190,7 @@ def my_method( return my_var async def my_async_method(self, my_param: ParameterT = "default_value") -> ReturnT: - """An :term:`async` method. + """An :py::keyword:`async` method. Text at end of docstring. """ diff --git a/sample-docs/kitchen-sink/api.rst b/sample-docs/kitchen-sink/api.rst index d4cad5fb98..ab2182a7f1 100644 --- a/sample-docs/kitchen-sink/api.rst +++ b/sample-docs/kitchen-sink/api.rst @@ -7,12 +7,15 @@ API documentation ***************** - A domain is a collection of markup (directives and roles) to describe and link to objects belonging together, - e.g. elements of a programming language. +A domain is a collection of markup, consisting of directives and roles, +that describe and link to objects belonging together, +such as elements of a programming language. - -- https://www.sphinx-doc.org/en/master/usage/domains/index.html +.. seealso:: -The following sections show examples of the domains built-in to Sphinx. + `Domains `_ + +The following sections show examples of the built-in domains of Sphinx. .. toctree:: :titlesonly: @@ -23,7 +26,8 @@ The following sections show examples of the domains built-in to Sphinx. Using autodoc ============= -Using Sphinx's :any:`sphinx.ext.autodoc` plugin, it is possible to auto-generate documentation of a Python module. +Using Sphinx's :any:`sphinx.ext.autodoc` plugin, +it is possible to auto-generate documentation of a Python module. .. tip:: Avoid having in-function-signature type annotations with autodoc, @@ -45,9 +49,18 @@ Using Sphinx's :any:`sphinx.ext.autodoc` plugin, it is possible to auto-generate The ``automodule`` Directive with reStructuredText Markup --------------------------------------------------------- -What follows after the line is an example showing usage of the ``.. automodule::`` directive. +The following markup is an example of the ``automodule`` directive. +Note that the ``currentmodule`` directive sets the current module. + +.. code-block:: rst + + .. currentmodule:: all_in_one_restructuredtext + + .. automodule:: all_in_one_restructuredtext + :members: + :member-order: bysource ---- +The foregoing markup example renders as shown below. .. currentmodule:: all_in_one_restructuredtext From 5b6d05477281c81bd9bc1506c244417f7a758aa1 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Sun, 3 Aug 2025 22:05:05 +0200 Subject: [PATCH 3/5] Update sample-docs/kitchen-sink/all_in_one_restructuredtext.py Co-authored-by: Steve Piercy --- sample-docs/kitchen-sink/all_in_one_restructuredtext.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py index 29f17a230e..481601422a 100644 --- a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py +++ b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py @@ -190,7 +190,7 @@ def my_method( return my_var async def my_async_method(self, my_param: ParameterT = "default_value") -> ReturnT: - """An :py::keyword:`async` method. + """An :py:keyword:`async` method. Text at end of docstring. """ From 8983a8aa16fd642958d00638122e526fa824a638 Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Mon, 4 Aug 2025 17:04:06 +0200 Subject: [PATCH 4/5] Remove TODO comments These will become proper GitHub issues --- sample-docs/kitchen-sink/all_in_one_restructuredtext.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py index 481601422a..58b04ab7a1 100644 --- a/sample-docs/kitchen-sink/all_in_one_restructuredtext.py +++ b/sample-docs/kitchen-sink/all_in_one_restructuredtext.py @@ -4,11 +4,6 @@ The module's docstrings use reStructuredText markup. """ -# TODO: -# - show the roles to refer to the listed directives -# - missing: async with, async for -# - add example(s) of numpy-style docstrings - import abc from typing import TypeAlias, TypeVar, final From 0e2096480336b9774fc035bc1b115852e463f48d Mon Sep 17 00:00:00 2001 From: Colin Marquardt Date: Mon, 4 Aug 2025 20:54:57 +0200 Subject: [PATCH 5/5] Add python3 to intersphinx and use better URL for sphinx-doc.org --- src/templates/conf.template.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/templates/conf.template.py b/src/templates/conf.template.py index 1314e7ec16..c0beb273f9 100644 --- a/src/templates/conf.template.py +++ b/src/templates/conf.template.py @@ -30,7 +30,8 @@ } intersphinx_mapping = { - "sphinx": ("https://www.sphinx-doc.org/", None), + "python": ("https://docs.python.org/3/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), } todo_include_todos = True