fix: drop title

Signed-off-by: Henry Schreiner <[email protected]>

.pre-commit-config.yaml

@@ -30,7 +30,11 @@ repos:
   - id: mypy
     files: ^(src|tests)
     args: [--show-error-codes]
-    additional_dependencies: [numpy~=1.23.0, pytest, importlib_metadata]
+    additional_dependencies:
+      - numpy~=1.23.0
+      - pytest
+      - importlib_metadata
+      - importlib_resources
 
 - repo: https://github.com/pre-commit/pygrep-hooks
   rev: v1.10.0

docs/conf.py

@@ -8,16 +8,6 @@
 
 import sys
 
-# -- Path setup --------------------------------------------------------------
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 if sys.version_info < (3, 8):
     import importlib_metadata as metadata
 else:
@@ -31,7 +21,7 @@
 author = "Henry Schreiner, Hans Dembinski, Jim Pivarski"
 
 # The full version, including alpha/beta/rc tags
-release = metadata.version("uhi")
+version = release = metadata.version("uhi")
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,10 +30,13 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "myst_parser",
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
 ]
 
+source_suffix = [".rst", ".md"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -52,25 +45,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_book_theme"
-
-html_baseurl = "https://uhi.readthedocs.io/en/latest/"
-
-html_theme_options = {
-    "home_page_in_toc": True,
-    "repository_url": "https://github.com/scikit-hep/uhi",
-    "use_repository_button": True,
-    "use_issues_button": True,
-    "use_edit_page_button": True,
-}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []  # _static
+html_theme = "furo"

docs/index.rst

@@ -30,6 +30,7 @@ to plot a histogram, including error bars.
    indexing.rst
    indexing+.rst
    plotting.rst
+   serialization.md
 
 
 

docs/serialization.md

@@ -0,0 +1,7 @@
+# Serialization
+
+A standard form of serialization is described as follows:
+
+```{literalinclude} ../src/uhi/resources/histogram.json
+:language: json
+```

noxfile.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import re
 from pathlib import Path
 
@@ -31,22 +32,34 @@ def tests(session):
     session.run("pytest", *session.posargs)
 
 
-@nox.session
-def docs(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.
     """
 
-    session.install(".[docs]")
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serve", action="store_true", help="Serve after building")
+    args, posargs = parser.parse_known_args(session.posargs)
+
+    session.install("-e.[docs]")
     session.chdir("docs")
-    session.run("sphinx-build", "-M", "html", ".", "_build")
-
-    if session.posargs:
-        if "serve" in session.posargs:
-            print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
-            session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
-        else:
-            print("Unsupported argument to docs")
+
+    session.run(
+        "sphinx-build",
+        "-n",  # nitpicky mode
+        "--keep-going",  # show all errors
+        "-T",  # full tracebacks
+        "-b",
+        "html",
+        ".",
+        "_build/html",
+        *posargs,
+    )
+
+    if args.serve:
+        session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
+        session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
 
 
 @nox.session

pyproject.toml

@@ -49,8 +49,9 @@ schema = [
 ]
 docs = [
   "sphinx>=4.0",
-  "sphinx-book-theme>=0.0.40",
+  "furo",
   "sphinx-copybutton>=0.3.1",
+  "myst-parser",
 ]
 test = [
   "pytest>=6",
@@ -85,6 +86,10 @@ python_version = "3.8"
 warn_unused_configs = "true"
 strict = true
 
+[[tool.mypy.overrides]]
+module = ["fastjsonschema"]
+ignore_missing_imports = true
+
 [tool.ruff]
 select = [
   "E", "F", "W", # flake8

src/uhi/resources/histogram.json

@@ -1,14 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/scikit-hep/uhi/.json",
+  "$id": "https://raw.githubusercontent.com/scikit-hep/uhi/henryiii/feat/schema/src/uhi/resources/histogram.json",
   "type": "object",
   "patternProperties": {
     ".+": {
       "type": "object",
       "required": ["axes", "storage"],
       "properties": {
-        "title": { "type": "string" },
-        "name": { "type": "string" },
         "metadata": { "type": "object" },
         "axes": {
           "type": "array",
@@ -47,7 +45,6 @@
         "overflow": { "type": "boolean" },
         "circular": { "type": "boolean" },
         "name": { "type": "string" },
-        "title": { "type": "string" },
         "metadata": { "type": "object" }
       }
     },
@@ -71,7 +68,6 @@
         "overflow": { "type": "boolean" },
         "circular": { "type": "boolean" },
         "name": { "type": "string" },
-        "title": { "type": "string" },
         "metadata": { "type": "object" }
       }
     },
@@ -83,7 +79,6 @@
         "categories": { "type": "array", "items": { "type": "string" } },
         "flow": { "type": "boolean" },
         "name": { "type": "string" },
-        "title": { "type": "string" },
         "metadata": { "type": "object" }
       }
     },
@@ -95,7 +90,6 @@
         "categories": { "type": "array", "items": { "type": "number" } },
         "flow": { "type": "boolean" },
         "name": { "type": "string" },
-        "title": { "type": "string" },
         "metadata": { "type": "object" }
       }
     },
@@ -105,7 +99,6 @@
       "properties": {
         "type": { "type": "string", "pattern": "boolean" },
         "name": { "type": "string" },
-        "title": { "type": "string" },
         "metadata": { "type": "object" }
       }
     },

src/uhi/schema.py

@@ -2,6 +2,7 @@
 
 import json
 import sys
+from pathlib import Path
 
 import fastjsonschema
 
@@ -16,8 +17,9 @@
     histogram_schema = fastjsonschema.compile(json.load(f))
 
 
-def validate(path: str) -> None:
-    with open(path, encoding="utf-8") as f:
+def validate(path: str | Path) -> None:
+    path = Path(path)
+    with path.open(encoding="utf-8") as f:
         example = json.load(f)
 
     histogram_schema(example)