Add section on docs with type annotations.

Author: TallJimbo

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

@@ -0,0 +1,86 @@
+.. _stack-documentation-code-with-type-hints:
+
+################################
+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.
+
+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.
+
+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 and the return type is annotated.
+When the returned object does 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 ""
+
+The return type does not need backticks to create a link, but backticks may be used, e.g. for a generic type:
+
+   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 `Sphinx's own target-resolution rules <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-resolution>``__.  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)
+
+.. _`Documenteer 2`: https://documenteer.lsst.io
+.. _`sphinx-autodoc-typehints`: https://pypi.org/project/sphinx-autodoc-typehints/
+.. _`pipelines.lsst.io`: https://pipelines.lsst.io

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`