From 8ef07e68692a0f19a79954ad4f93da98fd7937a9 Mon Sep 17 00:00:00 2001 From: Jim Bosch Date: Tue, 3 Feb 2026 11:21:58 -0500 Subject: [PATCH 1/5] Make the note on Sphinx Python name resolution more prominent. Almost nobody knows that Sphinx normally pays no attention to your import statements, and I didn't even notice the existing text on this when I went to add new text on it. --- restructuredtext/style.rst | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/restructuredtext/style.rst b/restructuredtext/style.rst index c8bb7d2b..fb5034a2 100644 --- a/restructuredtext/style.rst +++ b/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 `__. + 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 `_ 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: From bb201248133f41513814e6970f62f9cdb200d55a Mon Sep 17 00:00:00 2001 From: Jim Bosch Date: Tue, 3 Feb 2026 11:23:19 -0500 Subject: [PATCH 2/5] Add section on docs with type annotations. --- index.rst | 3 + ...documenting-code-with-type-annotations.rst | 117 ++++++++++++++++++ stack/index.rst | 1 + 3 files changed, 121 insertions(+) create mode 100644 stack/documenting-code-with-type-annotations.rst diff --git a/index.rst b/index.rst index 7d84ba8b..48519108 100644 --- a/index.rst +++ b/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` diff --git a/stack/documenting-code-with-type-annotations.rst b/stack/documenting-code-with-type-annotations.rst new file mode 100644 index 00000000..c7ab5009 --- /dev/null +++ b/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 ` 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`: ` diff --git a/stack/index.rst b/stack/index.rst index 885a1b35..32e0177f 100644 --- a/stack/index.rst +++ b/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` From 1f76c5d40f330038b02e3604b01591b02f3083e7 Mon Sep 17 00:00:00 2001 From: Jim Bosch Date: Tue, 3 Feb 2026 15:42:16 -0500 Subject: [PATCH 3/5] Tuple returns should use types, not labels. This is not clear from the Sphinx output unless you know what you're looking for, but nitpick mode complains if you don't use types. --- stack/documenting-code-with-type-annotations.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/stack/documenting-code-with-type-annotations.rst b/stack/documenting-code-with-type-annotations.rst index c7ab5009..0ba7cbf5 100644 --- a/stack/documenting-code-with-type-annotations.rst +++ b/stack/documenting-code-with-type-annotations.rst @@ -74,16 +74,17 @@ A simple return type does not need backticks to create a link, but backticks may 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:: +Functions that return multiple values via a tuple should just have multiple +entries:: def return_pair() -> tuple[str, int]: """Return a pair. Returns ------- - name + str The name. - id + int The ID. """ return ("", 0) From 8112aed5a71fdf5e2c0b477db0a27203f2b804dd Mon Sep 17 00:00:00 2001 From: Jim Bosch Date: Tue, 3 Feb 2026 15:52:06 -0500 Subject: [PATCH 4/5] Add recommendations on documenting generics. --- ...documenting-code-with-type-annotations.rst | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/stack/documenting-code-with-type-annotations.rst b/stack/documenting-code-with-type-annotations.rst index 0ba7cbf5..ec687652 100644 --- a/stack/documenting-code-with-type-annotations.rst +++ b/stack/documenting-code-with-type-annotations.rst @@ -74,8 +74,7 @@ A simple return type does not need backticks to create a link, but backticks may 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:: +Functions that return multiple values via a tuple should just have multiple entries:: def return_pair() -> tuple[str, int]: """Return a pair. @@ -111,8 +110,33 @@ Their docstrings should continue to include the types parenthetically:: 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`: ` +.. _`generics`: From 98613b8b2db6b39cb884d8f3b2a2e812aee1c891 Mon Sep 17 00:00:00 2001 From: Jim Bosch Date: Tue, 3 Feb 2026 16:01:05 -0500 Subject: [PATCH 5/5] Fix some unnecessary line breaks. --- stack/documenting-code-with-type-annotations.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/stack/documenting-code-with-type-annotations.rst b/stack/documenting-code-with-type-annotations.rst index ec687652..4209f47e 100644 --- a/stack/documenting-code-with-type-annotations.rst +++ b/stack/documenting-code-with-type-annotations.rst @@ -14,8 +14,7 @@ Documentation built with `Documenteer 2.x`_ can often leave this information out 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:: +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. @@ -106,8 +105,7 @@ Their docstrings should continue to include the types parenthetically:: """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. + 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