Fix some small things

sample-docs/kitchen-sink/all_in_one_restructuredtext.py

@@ -4,24 +4,26 @@
 The module's docstrings use reStructuredText markup.
 """
 
-# TODO:
-# - show roles to refer to elements
-# - async with
-# - async for
-# - add example 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`."""
+
+# type MyType = list[
+#     float
+# ]  #: The docstring of :py:type:`MyType` using Python 3.12 syntax.
 
-# Python 3.12: type MyType = list[float]  #: The docstring.
-MyType: TypeAlias = list[float]  #: 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.
+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):
@@ -105,8 +107,9 @@ def my_function2(foo: int, bar: str):
     Returns:
         None
 
-    .. deprecated:: 2.0
-        Use :func:`my_function_pure_sphinx` instead.
+    .. deprecated:: x.y
+        (This is an example of a deprecation admonition.)
+        Use :py:func:`my_function_pure_sphinx` instead.
 
     Text at end of docstring.
     """
@@ -131,7 +134,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:
@@ -160,9 +163,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``.
@@ -180,7 +185,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.
         """

sample-docs/kitchen-sink/api.rst

@@ -7,6 +7,16 @@
 API documentation
 *****************
 
+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.
+
+.. seealso::
+
+    `Domains <https://www.sphinx-doc.org/en/master/usage/domains/index.html>`_
+
+The following sections show examples of the built-in domains of Sphinx.
+
 .. toctree::
     :titlesonly:
     :glob:
@@ -16,7 +26,8 @@ API documentation
 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,
@@ -38,7 +49,18 @@ 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.
+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
 

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