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,117 @@
+.. _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 have their return types documented just like parameters, i.e. with labels and no types::
+
+   def return_pair() -> tuple[str, int]:
+       """Return a pair.
+
+       Returns
+       -------
+       name
+           The name.
+       id
+           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.
+
+
+.. _`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>`

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`