rework docs a bit; add partitioned_factory to top level namespace

Author: douglasdavis

.gitignore

@@ -89,6 +89,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
 
 # PyBuilder
 target/

docs/api.rst

@@ -5,16 +5,23 @@ Collection API
 ^^^^^^^^^^^^^^
 
 .. currentmodule:: dask_histogram
+
 .. autosummary::
+   :toctree: generated/
+
    AggHistogram
    PartitionedHistogram
    factory
+   partitioned_factory
 
 dask.array/NumPy-like API
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. currentmodule:: dask_histogram.routines
+
 .. autosummary::
+   :toctree: generated/
+
    histogram
    histogram2d
    histogramdd
@@ -23,27 +30,31 @@ boost-histogram-like API
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. currentmodule:: dask_histogram.boost
-.. autosummary::
-   Histogram
 
-Reference
-^^^^^^^^^
-
-.. currentmodule:: dask_histogram
-.. autofunction:: factory
-.. autoclass:: AggHistogram
-   :members:
-   :autosummary:
-.. autoclass:: PartitionedHistogram
-   :members:
-   :autosummary:
+.. autosummary::
+   :toctree: generated/
 
-.. currentmodule:: dask_histogram.routines
-.. autofunction:: histogram
-.. autofunction:: histogram2d
-.. autofunction:: histogramdd
+   Histogram
 
-.. currentmodule:: dask_histogram.boost
-.. autoclass:: Histogram
-   :members:
-   :autosummary:
+..
+   Reference
+   ^^^^^^^^^
+
+   .. currentmodule:: dask_histogram
+   .. autofunction:: factory
+   .. autoclass:: AggHistogram
+      :members:
+      :autosummary:
+   .. autoclass:: PartitionedHistogram
+      :members:
+      :autosummary:
+
+   .. currentmodule:: dask_histogram.routines
+   .. autofunction:: histogram
+   .. autofunction:: histogram2d
+   .. autofunction:: histogramdd
+
+   .. currentmodule:: dask_histogram.boost
+   .. autoclass:: Histogram
+      :members:
+      :autosummary:

src/dask_histogram/__init__.py

@@ -3,7 +3,12 @@
 import boost_histogram.axis as _axis
 import boost_histogram.storage as _storage
 
-from dask_histogram.core import AggHistogram, PartitionedHistogram, factory
+from dask_histogram.core import (
+    AggHistogram,
+    PartitionedHistogram,
+    factory,
+    partitioned_factory,
+)
 from dask_histogram.routines import histogram, histogram2d, histogramdd
 from dask_histogram.version import __version__
 
@@ -27,5 +32,6 @@
     "histogram",
     "histogram2d",
     "histogramdd",
+    "partitioned_factory",
     "storage",
 )

src/dask_histogram/core.py

@@ -617,7 +617,7 @@ def _partitioned_histogram(
 ) -> PartitionedHistogram:
     name = f"hist-on-block-{tokenize(data, histref, weights, sample, split_every)}"
     data_is_df = is_dataframe_like(data[0])
-    data_is_dak = is_awkward_like(data[0])
+    data_is_dak = is_dask_awkward_like(data[0])
     _weight_sample_check(*data, weights=weights)
 
     # Single awkward array object.
@@ -832,8 +832,7 @@ def factory(
     split_every : int, optional
         How many blocks to use in each split during aggregation.
     keep_partitioned : bool, optional
-        If ``True``, return the partitioned histogram collection
-        instead of an aggregated histogram.
+        **Deprecated argument**. Use :py:func:`partitioned_factory`.
 
     Returns
     -------
@@ -911,6 +910,18 @@ def partitioned_factory(
     weights: DaskCollection | None = None,
     sample: DaskCollection | None = None,
 ) -> PartitionedHistogram:
+    """Daskified Histogram collection factory function; keep partitioned.
+
+    This is a version of the :py:func:`factory` function that **remains
+    partitioned**. The :py:func:`factory` function includes a step in the
+    task graph that aggregates all partitions into a single final
+    histogram.
+
+    See Also
+    --------
+    dask_histogram.factory
+
+    """
     if histref is None and axes is None:
         raise ValueError("Either histref or axes must be defined.")
     if histref is not None and storage is not None:
@@ -925,7 +936,7 @@ def partitioned_factory(
     )
 
 
-def is_awkward_like(x: Any) -> bool:
+def is_dask_awkward_like(x: Any) -> bool:
     """Check if an object is Awkward collection like.
 
     Parameters