DM-54027: add docs on writing docs with type annotations

index.rst

@@ -335,6 +335,7 @@ ReStructuredText
    stack/documentation-system-overview
    stack/layout-of-doc-directory
    stack/package-documentation-topic-types
+   stack/documenting-code-with-type-annotations
    stack/add-a-package-to-pipelines-lsst-io
    stack/building-single-package-docs
    stack/building-pipelines-lsst-io-locally
@@ -385,6 +386,8 @@ Documentation.
     - :doc:`stack/argparse-script-topic-type`
     - :doc:`stack/generic-guide-topic-type`
 
+  - :doc:`stack/documenting-code-with-type-annotations`
+
 - Documentation in the main repository:
 
   - :doc:`stack/add-a-package-to-pipelines-lsst-io`

restructuredtext/style.rst

@@ -356,13 +356,37 @@ Objects can be referenced with these roles:
 - ``:py:data:`pkg.mod.VARIABLE``` to reference a module-level variable ``VARIABLE`` in ``pkg.mod``.
 - ``:py:const:`pkg.mod.CONSTANT``` to reference a module-level *constant* ``CONSTANT`` in ``pkg.mod``.
 
-Namespace resolution
-""""""""""""""""""""
+.. note::
+   Types in docstrings do *not* respect imports in the file, and instead are resolved using `Sphinx's own target-resolution rules <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-resolution>`__.
+   In other words,
+
+   .. code-block::
+
+      from collections.abc import Sequence
+
+      def run_stuff(stuff):
+          """Run some stuff.
+
+          Parameters
+          ----------
+          stuff : `Sequence` [`str`]
+              Stuff to run.
+
+   does not work, but
+
+   .. code-block::
+
+      from collections.abc import Sequence
+
+      def run_stuff(stuff):
+          """Run some stuff.
+
+          Parameters
+          ----------
+          stuff : `~collections.abc.Sequence` [`str`]
+              Stuff to run.
 
-In these examples, the full namespace of each Python object is specified.
-In some contexts, Sphinx may be able to identify the reference object without the full namespace.
-For example in class docstrings, references to methods or attributes in the same class can be made by name alone.
-See the `Sphinx documentation <http://sphinx-doc.org/domains.html#cross-referencing-python-objects>`_ for more details on object resolution.
+   does.  See the link above for how to make relative links to types; the syntax is not the same as Python's, and it operates on the documentation hierarchy, not the module hierarchy.
 
 .. _rst-cpp-links:
 

stack/documenting-code-with-type-annotations.rst

@@ -0,0 +1,140 @@
+.. _stack-documentation-code-with-type-annotations:
+
+################################
+Documenting code with type hints
+################################
+
+Many DM packages (especially the middleware suite) use type hints for static analysis, which often duplicates the type information included in docstrings.
+Documentation built with `Documenteer 2.x`_ can often leave this information out, because the `sphinx-autodoc-typehints`_ extension (included automatically) will parse the annotations and include type information in the docs automatically.
+
+.. note::
+   `pipelines.lsst.io`_ is currently still built with Documenteer 1.x, but is expected to transition soon.
+   While some :ref:`package doc builds <build-package-docs>` have already been upgraded in anticipation of this transition, their documentation content needs to remain compatible with Documenteer 1.x for now.
+
+Function arguments
+------------------
+
+To document the parameters to a function or method declared with type hints, use regular numpydoc style without the colon or the type information that follows it::
+
+   def run_thing(self, x: int, *args: int, name: str = "", **kwargs: str) -> None:
+       """Run the thing.
+
+       Parameters
+       ----------
+       x
+           X coordinate.
+       *args
+           Some other coordinates.
+       name
+           The name of the thing.
+       **kwargs
+           Names of other things.
+       """
+
+Note that ``, optional`` is also unnecessary, as are defaults; default values are automatically pulled from the real function signature.
+
+Function return values
+----------------------
+
+Return types work automatically when they are not documented at all::
+
+   def return_it() -> str:
+       """Return the thing."""
+       return ""
+
+This is a reasonable approach when there is nothing else to document about the returned object.
+When the returned object does merit additional documentation, the type does unfortunately need to be written out (duplicating the annotation), but the returned object should not be named::
+
+   def return_it() -> str:
+       """Return the thing.
+
+       Returns
+       -------
+       str
+           The thing.
+       """
+       return ""
+
+A simple return type does not need backticks to create a link, but backticks may be needed for more complex types (e.g. generics)::
+
+   from collections.abc import Sequence
+
+   def return_stuff() -> Sequence[str]:
+       """Return some stuff.
+
+       Returns
+       -------
+       `~collections.abc.Sequence` [`str`]
+           The stuff.
+       """
+       return []
+
+.. note::
+   As always, types in docstrings do *not* respect imports in the file, and instead are resolved using the `Sphinx target-resolution rules`_.
+   See :ref:`rst-python-link` for details.
+
+Functions that return multiple values via a tuple should just have multiple entries::
+
+   def return_pair() -> tuple[str, int]:
+       """Return a pair.
+
+       Returns
+       -------
+       str
+           The name.
+       int
+           The ID.
+       """
+       return ("", 0)
+
+Properties and attributes
+-------------------------
+
+Annotations on properties and attributes are not applied to documentation automatically.
+Their docstrings should continue to include the types parenthetically::
+
+   class Thing:
+       """A thing."""
+
+       @property
+       def name(self) -> str:
+           """Name of the thing (`str`)."""
+           return ""
+
+       value: int = 0
+       """Value of the thing (`int`)."""
+
+.. note::
+   Attributes without default values (or some sort of ``= RHS``) are not included in documentation *at all*, except for those on `~dataclasses.dataclass` types.
+   Important instance attributes that cannot have a class-level default value should be made into properties so they can be documented.
+
+Generics
+--------
+
+Functions that use `generics`_ will appear in the documentation with the type variable as the type, but these do not resolve to any kind of link, and in nitpick mode Sphinx will warn about those broken links.
+These should be included in the ``nitpick-ignore`` section of ``documenteer.toml``:
+
+.. code-block:: toml
+   [sphinx]
+   nitpick_ignore = [
+       ["py:class", "T"],  # type variables don't resolve
+   ]
+
+for e.g.::
+
+   def generic[T: int | float](value: T) -> T:
+       """Do something with a value.
+
+       Parameters
+       ----------
+       value
+           The given value (a `float` or `int`).
+       """
+
+Since the automatic docstrings do not include any information about a bound on the type variable (i.e. ``int | float`` here), including that information in the description is recommended.
+
+.. _`Documenteer 2.x`: https://documenteer.lsst.io
+.. _`sphinx-autodoc-typehints`: https://pypi.org/project/sphinx-autodoc-typehints/
+.. _`pipelines.lsst.io`: https://pipelines.lsst.io
+.. _`Sphinx target-resolution rules`: <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-resolution>`
+.. _`generics`: <https://docs.python.org/3/library/typing.html#generics>

stack/index.rst

@@ -12,6 +12,7 @@ DM Stack guides
 - :doc:`documentation-system-overview`
 - :doc:`layout-of-doc-directory`
 - :doc:`package-documentation-topic-types`
+- :doc:`documenting-code-with-type-annotations`
 - :doc:`add-a-package-to-pipelines-lsst-io`
 - :doc:`building-single-package-docs`
 - :doc:`building-pipelines-lsst-io-locally`