style: add blacken docs

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

.pre-commit-config.yaml

@@ -8,6 +8,12 @@ repos:
     hooks:
       - id: black-jupyter
 
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: "1.16.0"
+    hooks:
+      - id: blacken-docs
+        additional_dependencies: [black==23.7.0]
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:

README.md

@@ -60,7 +60,7 @@ values = hist.values()
 
 # Make a new histogram with just the second axis, summing over the first, and
 # rebinning the second into larger bins:
-h2 = hist[::sum, ::bh.rebin(2)]
+h2 = hist[::sum, :: bh.rebin(2)]
 ```
 
 </details>

docs/banner_slides.md

@@ -1,6 +1,7 @@
 ---
 aspectratio: 169
 fontfamily: bookman
+orphan: true
 ---
 
 # Simple usage
@@ -16,12 +17,10 @@ Converted to GIF with ezgif.com, 300 ms delay time.
 import boost_histogram as bh
 
 # Make a histogram
-h = bh.Histogram(
-    bh.axis.Regular(10, 0, 1)
-)
+h = bh.Histogram(bh.axis.Regular(10, 0, 1))
 
 # Fill it with events
-h.fill([.2, .3, .6, .9])
+h.fill([0.2, 0.3, 0.6, 0.9])
 
 # Compute the sum
 total = h.sum()
@@ -31,10 +30,10 @@ total = h.sum()
 
 ```python
 # Slice in data coordinates
-sliced_h = h[bh.loc(.5):bh.loc(1.5)]
+sliced_h = h[bh.loc(0.5) : bh.loc(1.5)]
 
 # Sum over and rebin easily
-smaller = h[::sum, ::bh.rebin(2)]
+smaller = h[::sum, :: bh.rebin(2)]
 
 # Set and access easily
 h[...] = np.asarray(prebinned)
@@ -87,6 +86,7 @@ Supports the UHI `PlottableHistogram` protocol!
 
 ```python
 import mplhep
+
 mplhep.histplot(h)
 ```
 

docs/changelog.md

@@ -449,7 +449,6 @@ usability when plotting and indexing.
 
 - Histograms support operations with arrays, no longer take the first element only [#417][]
 
-[#414]: https://github.com/scikit-hep/boost-histogram/pull/414
 [#414]: https://github.com/scikit-hep/boost-histogram/pull/414
 [#415]: https://github.com/scikit-hep/boost-histogram/pull/415
 [#417]: https://github.com/scikit-hep/boost-histogram/pull/417

docs/conf.py

@@ -46,10 +46,11 @@
 # ones.
 extensions = [
     "myst_parser",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
     "nbsphinx",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
     "sphinx_copybutton",
 ]
 
@@ -71,6 +72,12 @@
 # Read the Docs needs this explicitly listed.
 master_doc = "index"
 
+# Intersphinx setup
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
 # -- Options for Notebook input ----------------------------------------------
 
 html_logo = "_images/BoostHistogramPythonLogo.png"

docs/index.rst

@@ -36,12 +36,10 @@ virtual environment, etc. See :ref:`usage-installation` for more details. An exa
    import boost_histogram as bh
 
    # Compose axis however you like; this is a 2D histogram
-   hist = bh.Histogram(bh.axis.Regular(2, 0, 1),
-                       bh.axis.Regular(4, 0.0, 1.0))
+   hist = bh.Histogram(bh.axis.Regular(2, 0, 1), bh.axis.Regular(4, 0.0, 1.0))
 
    # Filling can be done with arrays, one per dimension
-   hist.fill([.3, .5, .2],
-             [.1, .4, .9])
+   hist.fill([0.3, 0.5, 0.2], [0.1, 0.4, 0.9])
 
    # NumPy array view into histogram counts, no overflow bins
    counts = hist.view()

docs/user-guide/axes.rst

@@ -95,7 +95,6 @@ One common use for an integer axis could be a true/false axis:
 .. code-block:: python3
 
    bool_axis = bh.axis.Integer(0, 2, underflow=False, overflow=False)
-   :noindex:
 
 Another could be for an IntEnum if the values are contiguous.
 
@@ -117,12 +116,13 @@ One use for an IntCategory axis is for an IntEnum:
 
     import enum
 
+
     class MyEnum(enum.IntEnum):
         a = 1
         b = 5
 
+
     my_enum_axis = bh.axis.IntEnum(list(MyEnum), underflow=False, overflow=False)
-   :noindex:
 
 
 .. py:function:: bh.axis.StrCategory([str1, ...], metadata="", growth=False)

docs/user-guide/numpy.rst

@@ -41,13 +41,15 @@ If you try the following in an IPython session, you will get:
    import numpy as np
    import boost_histogram as bh
 
-   norm_vals = np.concatenate([
-       np.random.normal(loc=5, scale=1, size=1_000_000),
-       np.random.normal(loc=2, scale=.2, size=200_000),
-       np.random.normal(loc=8, scale=.2, size=200_000),
-   ])
+   norm_vals = np.concatenate(
+       [
+           np.random.normal(loc=5, scale=1, size=1_000_000),
+           np.random.normal(loc=2, scale=0.2, size=200_000),
+           np.random.normal(loc=8, scale=0.2, size=200_000),
+       ]
+   )
 
-.. code-block:: python3
+.. code-block:: ipython
 
    %%timeit
    bins, edges = np.histogram(norm_vals, bins=100, range=(0, 10))
@@ -64,7 +66,7 @@ ND histograms. But if you already use NumPy histograms and you really
 don’t want to rewrite your code, boost-histogram has adaptors for the
 three histogram functions in NumPy:
 
-.. code-block:: python3
+.. code-block:: ipython
 
    %%timeit
    bins, edges = bh.numpy.histogram(norm_vals, bins=100, range=(0, 10))
@@ -95,15 +97,12 @@ So you can transition your code slowly to boost-histogram.
 
 .. code-block:: python3
 
-   data  = np.random.multivariate_normal(
-       (0, 0),
-       ((1, 0),(0, .5)),
-       10_000_000).T.copy()
+   data = np.random.multivariate_normal((0, 0), ((1, 0), (0, 0.5)), 10_000_000).T.copy()
 
 We can check the performance against NumPy again; NumPy does not do well
 with regular spaced bins in more than 1D:
 
-.. code-block:: python3
+.. code-block:: ipython
 
    %%timeit
    np.histogram2d(*data, bins=(400, 200), range=((-2, 2), (-1, 1)))
@@ -112,7 +111,7 @@ with regular spaced bins in more than 1D:
 
    1.31 s ± 17.3 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
 
-.. code-block:: python3
+.. code-block:: ipython
 
    %%timeit
    bh.numpy.histogram2d(*data, bins=(400, 200), range=((-2, 2), (-1, 1)))

docs/user-guide/subclassing.rst

@@ -13,9 +13,11 @@ When you subclass, you will need to add a family. Any object can be used - the m
     import boost_histogram as bh
     import my_package
 
+
     class Histogram(bh.Histogram, family=my_package):
         ...
 
+
     class Regular(bh.axis.Regular, family=my_package):
         ...
 

docs/user-guide/transforms.rst

@@ -134,6 +134,7 @@ ctypes call into the convert function. You need a little wrapper function to mak
 
    import ctypes, math
 
+
    # We need a little wrapper function only because ftype is not directly picklable
    def convert_python(func):
        ftype = ctypes.CFUNCTYPE(ctypes.c_double, ctypes.c_double)

noxfile.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import shutil
 
 import nox
@@ -36,22 +37,46 @@ def hist(session: nox.Session) -> None:
     session.run("pytest", *session.posargs)
 
 
-@nox.session
+@nox.session(reuse_venv=True)
 def docs(session: nox.Session) -> None:
     """
-    Build the docs. Pass "serve" to serve.
+    Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links.
     """
 
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serve", action="store_true", help="Serve after building")
+    parser.add_argument(
+        "-b", dest="builder", default="html", help="Build target (default: html)"
+    )
+    args, posargs = parser.parse_known_args(session.posargs)
+
+    if args.builder != "html" and args.serve:
+        session.error("Must not specify non-HTML builder with --serve")
+
+    extra_installs = ["sphinx-autobuild"] if args.serve else []
+
     session.chdir("docs")
-    session.install("-r", "requirements.txt")
-    session.run("sphinx-build", "-M", "html", ".", "_build")
-
-    if session.posargs:
-        if "serve" in session.posargs:
-            session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
-            session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
-        else:
-            session.error("Unsupported argument to docs")
+    session.install("-r", "requirements.txt", *extra_installs)
+
+    if args.builder == "linkcheck":
+        session.run(
+            "sphinx-build", "-b", "linkcheck", ".", "_build/linkcheck", *posargs
+        )
+        return
+
+    shared_args = (
+        "-n",  # nitpicky mode
+        "-T",  # full tracebacks
+        f"-b={args.builder}",
+        ".",
+        f"_build/{args.builder}",
+        *posargs,
+    )
+
+    if args.serve:
+        session.run("sphinx-autobuild", *shared_args)
+    else:
+        session.run("sphinx-build", "--keep-going", *shared_args)
 
 
 @nox.session