Add documentation for DM-41605

doc/changes/DM-41605.feature.md

@@ -0,0 +1,7 @@
+Add functionality to aggregate multiple `QuantumProvenanceGraph.Summary`
+objects into one `Summary` for a wholistic report.
+
+While the `QuantumProvenanceGraph` was designed to resolve processing over
+dataquery-identified groups, `QuantumProvenanceGraph.aggregate` is designed to
+combine multiple group-level reports into one which totals the successes,
+issues and failures over the same section of pipeline.

python/lsst/pipe/base/quantum_provenance_graph.py

@@ -486,7 +486,13 @@ def add_quantum_info(self, info: QuantumInfo, butler: Butler, do_store_logs: boo
                 raise AssertionError(f"Unrecognized quantum status {unrecognized_state!r}")
 
     def add_data_id_group(self, other: TaskSummary) -> None:
-        """Docstring.
+        """Add information from a `TaskSummary` over one dataquery-identified
+        group to another, as part of aggregating `Summary` reports. 
+
+        Parameters
+        ----------
+        other : `TaskSummary`
+            `TaskSummary` to aggregate.
         """
         self.n_successful += other.n_successful
         self.n_blocked += other.n_blocked
@@ -639,7 +645,14 @@ def add_dataset_info(self, info: DatasetInfo, producer_info: QuantumInfo) -> Non
                 raise AssertionError(f"Unrecognized dataset status {unrecognized_state!r}")
 
     def add_data_id_group(self, other: DatasetTypeSummary) -> None:
-        """Docstring.
+        """Add information from a `DatasetTypeSummary` over one
+        dataquery-identified group to another, as part of aggregating `Summary`
+        reports. 
+
+        Parameters
+        ----------
+        other : `DatasetTypeSummary`
+            `DatasetTypeSummary` to aggregate.
         """
         if self.producer:
             # Guard against empty string
@@ -677,6 +690,11 @@ def aggregate(cls, summaries: Iterable[Summary]) -> Summary:
         """Combine summaries from disjoint data id groups into an overall
         summary of common tasks and datasets. Intended for use when the same
         pipeline has been run over all groups.
+
+        Parameters
+        ----------
+        summaries : `Iterable[Summary]`
+            Iterable of all `Summary` objects to aggregate.
         """
         result = cls()
         for summary in summaries:

tests/test_quantum_provenance_graph.py

@@ -31,10 +31,15 @@
 
 import unittest
 
-from lsst.pipe.base.quantum_provenance_graph import QuantumProvenanceGraph, Summary, TaskSummary, DatasetTypeSummary
+import lsst.utils.logging
+from lsst.pipe.base.quantum_provenance_graph import (
+    DatasetTypeSummary,
+    QuantumProvenanceGraph,
+    Summary,
+    TaskSummary,
+)
 from lsst.pipe.base.tests import simpleQGraph
 from lsst.utils.tests import temporaryDirectory
-import lsst.utils.logging
 
 expected_mock_datasets = [
     "add_dataset1",