Apply suggestions from code review

Co-authored-by: Steve Piercy <[email protected]>

Author: cmarqu

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.
         """

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 <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:
@@ -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