Merge branch 'tickets/DM-36162'

doc/changes/DM-36162.doc.md

@@ -0,0 +1,6 @@
+Loosened documentation of `QuantumGraph.inputQuanta` and `outputQuanta`.
+They are not guaranteed to be (and currently are not) lists, so the new documentation describes them as iterables.
+
+Documented `universe` constructor parameter to `QuantumGraph`.
+
+Brought `QuantumGraph` property docs in line with DM standards.

doc/conf.py

@@ -6,3 +6,5 @@
 html_short_title = project
 doxylink = {}
 exclude_patterns = ["changes/*"]
+
+intersphinx_mapping['networkx'] = ('https://networkx.org/documentation/stable/', None)  # noqa: F405

python/lsst/pipe/base/graph/graph.py

@@ -114,6 +114,9 @@ class QuantumGraph:
         Entries in this mapping should be able to be serialized in JSON.
     pruneRefs : iterable [ `DatasetRef` ], optional
         Set of dataset refs to exclude from a graph.
+    universe : `lsst.daf.butler.DimensionUniverse`, optional
+        The dimensions in which quanta can be defined. Need only be provided if
+        no quanta have data IDs.
     initInputs : `Mapping`, optional
         Maps tasks to their InitInput dataset refs. Dataset refs can be either
         resolved or non-resolved. Presently the same dataset refs are included
@@ -329,74 +332,53 @@ def _buildGraphs(
 
     @property
     def taskGraph(self) -> nx.DiGraph:
-        """Return a graph representing the relations between the tasks inside
-        the quantum graph.
-
-        Returns
-        -------
-        taskGraph : `networkx.Digraph`
-            Internal datastructure that holds relations of `TaskDef` objects
+        """A graph representing the relations between the tasks inside
+        the quantum graph (`networkx.DiGraph`).
         """
         return self._taskGraph
 
     @property
     def graph(self) -> nx.DiGraph:
-        """Return a graph representing the relations between all the
-        `QuantumNode` objects. Largely it should be preferred to iterate
-        over, and use methods of this class, but sometimes direct access to
-        the networkx object may be helpful
+        """A graph representing the relations between all the `QuantumNode`
+        objects (`networkx.DiGraph`).
 
-        Returns
-        -------
-        graph : `networkx.Digraph`
-            Internal datastructure that holds relations of `QuantumNode`
-            objects
+        The graph should usually be iterated over, or passed to methods of this
+        class, but sometimes direct access to the ``networkx`` object may be
+        helpful.
         """
         return self._connectedQuanta
 
     @property
     def inputQuanta(self) -> Iterable[QuantumNode]:
-        """Make a `list` of all `QuantumNode` objects that are 'input' nodes
-        to the graph, meaning those nodes to not depend on any other nodes in
-        the graph.
+        """The nodes that are inputs to the graph (iterable [`QuantumNode`]).
 
-        Returns
-        -------
-        inputNodes : iterable of `QuantumNode`
-            A list of nodes that are inputs to the graph
+        These are the nodes that do not depend on any other nodes in the
+        graph.
         """
         return (q for q, n in self._connectedQuanta.in_degree if n == 0)
 
     @property
     def outputQuanta(self) -> Iterable[QuantumNode]:
-        """Make a `list` of all `QuantumNode` objects that are 'output' nodes
-        to the graph, meaning those nodes have no nodes that depend them in
-        the graph.
+        """The nodes that are outputs of the graph (iterable [`QuantumNode`]).
 
-        Returns
-        -------
-        outputNodes : iterable of `QuantumNode`
-            A list of nodes that are outputs of the graph
+        These are the nodes that have no nodes that depend on them in the
+        graph.
         """
         return [q for q, n in self._connectedQuanta.out_degree if n == 0]
 
     @property
     def allDatasetTypes(self) -> Tuple[DatasetTypeName, ...]:
-        """Return all the `DatasetTypeName` objects that are contained inside
-        the graph.
+        """All the data set type names that are present in the graph
+        (`tuple` [`str`]).
 
-        Returns
-        -------
-        tuple of `DatasetTypeName`
-            All the data set type names that are present in the graph, not
-            including global init-outputs.
+        These types do not include global init-outputs.
         """
         return tuple(self._datasetDict.keys())
 
     @property
     def isConnected(self) -> bool:
-        """Return True if all of the nodes in the graph are connected, ignores
-        directionality of connections.
+        """Whether all of the nodes in the graph are connected, ignoring
+        directionality of connections (`bool`).
         """
         return nx.is_weakly_connected(self._connectedQuanta)
 
@@ -846,7 +828,11 @@ def saveUri(self, uri: ResourcePathExpression) -> None:
 
     @property
     def metadata(self) -> Optional[MappingProxyType[str, Any]]:
-        """ """
+        """Extra data carried with the graph (mapping [`str`] or `None`).
+
+        The mapping is a dynamic view of this object's metadata. Values should
+        be able to be serialized in JSON.
+        """
         if self._metadata is None:
             return None
         return MappingProxyType(self._metadata)
@@ -1278,12 +1264,14 @@ def iterTaskGraph(self) -> Generator[TaskDef, None, None]:
 
     @property
     def graphID(self) -> BuildId:
-        """Returns the ID generated by the graph at construction time"""
+        """The ID generated by the graph at construction time (`str`)."""
         return self._buildId
 
     @property
     def universe(self) -> DimensionUniverse:
-        """Dimension universe associated with this graph."""
+        """Dimension universe associated with this graph
+        (`~lsst.daf.butler.DimensionUniverse`).
+        """
         return self._universe
 
     def __iter__(self) -> Generator[QuantumNode, None, None]: