docs: prepare for schema addition (#113)

* chore: prepare for schema addition Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * chore: bump pre-commit Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * ci: prepare for release and Python 3.12 Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
scikit-hep · Oct 16, 2023 · 08b7d65 · 08b7d65
1 parent 392b832
commit 08b7d65
Show file tree

Hide file tree

Showing 6 changed files with 142 additions and 130 deletions.
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -0,0 +1,39 @@
+name: CD
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  release:
+    types:
+    - published
+
+jobs:
+  dist:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - uses: hynek/build-and-inspect-python-package@v1
+
+
+  publish:
+    needs: [dist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uhi
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/download-artifact@v3
+      with:
+        name: Packages
+        path: dist
+
+    - uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -5,17 +5,11 @@ on:
   pull_request:
   push:
     branches:
-    - master
     - main
-    - develop
-  # TODO: release needs to be a separate workflow
-  release:
-    types:
-      - published
 
 concurrency:
-│      group: ${{ github.workflow }}-${{ github.ref }}
-│      cancel-in-progress:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
 
 jobs:
   checks:
@@ -24,11 +18,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.11"]
+        python-version: ["3.7", "3.12"]
         runs-on: [ubuntu-latest, macos-latest, windows-latest]
 
         include:
-        - python-version: pypy-3.8
+        - python-version: pypy-3.9
           runs-on: ubuntu-latest
         - python-version: "3.7"
           runs-on: ubuntu-20.04
@@ -74,26 +68,3 @@ jobs:
 
     - name: Test root
       run: pytest -ra tests/test_root.py
-
-
-
-  dist:
-    name: Distribution build
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - name: Build sdist and wheel
-      run: pipx run build
-
-    - uses: actions/upload-artifact@v3
-      with:
-        path: dist
-
-    - uses: pypa/gh-action-pypi-publish@release/v1
-      if: github.event_name == 'release' && github.event.action == 'published'
-      with:
-        password: ${{ secrets.pypi_password }}
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,56 +2,67 @@ ci:
   autoupdate_commit_msg: 'chore: update pre-commit hooks'
 
 repos:
-- repo: https://github.com/psf/black-pre-commit-mirror
-  rev: 23.9.1
-  hooks:
-  - id: black
-
-- repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
-  hooks:
-  - id: check-added-large-files
-  - id: check-case-conflict
-  - id: check-merge-conflict
-  - id: check-symlinks
-  - id: check-yaml
-  - id: debug-statements
-  - id: end-of-file-fixer
-  - id: mixed-line-ending
-  - id: requirements-txt-fixer
-  - id: trailing-whitespace
-
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: "v0.0.292"
-  hooks:
-    - id: ruff
-      args: ["--fix", "--show-fixes"]
-
-- repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.5.1
-  hooks:
-  - id: mypy
-    files: ^(src|tests)
-    args: [--show-error-codes]
-    additional_dependencies: [numpy~=1.23.0, pytest, importlib_metadata]
-
-- repo: https://github.com/pre-commit/pygrep-hooks
-  rev: v1.10.0
-  hooks:
-  - id: rst-backticks
-  - id: rst-directive-colons
-  - id: rst-inline-touching-normal
-
-- repo: https://github.com/codespell-project/codespell
-  rev: v2.2.6
-  hooks:
-  - id: codespell
-    args: ["-L", "hist,thist,ans,nd,gaus"]
-
-- repo: local
-  hooks:
-  - id: disallow-caps
-    name: Disallow improper capitalization
-    language: pygrep
-    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
-    exclude: .pre-commit-config.yaml
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 23.9.1
+    hooks:
+    - id: black
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    - id: check-added-large-files
+    - id: check-case-conflict
+    - id: check-merge-conflict
+    - id: check-symlinks
+    - id: check-yaml
+    - id: debug-statements
+    - id: end-of-file-fixer
+    - id: mixed-line-ending
+    - id: requirements-txt-fixer
+    - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.0.292"
+    hooks:
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.6.0
+    hooks:
+    - id: mypy
+      files: ^(src|tests)
+      args: []
+      additional_dependencies:
+        - numpy~=1.23.0
+        - pytest
+        - importlib_metadata
+        - importlib_resources
+
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+    - id: codespell
+      args: ["-L", "hist,thist,ans,nd,gaus"]
+
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+        exclude: .pre-commit-config.yaml
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.0.3"
+    hooks:
+      - id: prettier
+        types_or: [json]
diff --git a/docs/conf.py b/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,8 @@
 # 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"
diff --git a/noxfile.py b/noxfile.py
@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import argparse
 import re
 from pathlib import Path
 
 import nox
 
-ALL_PYTHONS = ["3.6", "3.7", "3.8", "3.9", "3.10"]
+ALL_PYTHONS = ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
 nox.options.sessions = ["lint", "tests"]
 
@@ -27,26 +28,38 @@ def tests(session):
     """
     Run the unit and regular tests.
     """
-    session.install(".[test]")
+    session.install("-e.[test]")
     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

diff --git a/pyproject.toml b/pyproject.toml
@@ -31,6 +31,7 @@ classifiers = [
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
   "Topic :: Scientific/Engineering",
   "Typing :: Typed",
 ]
@@ -45,8 +46,9 @@ Changelog = "https://github.com/scikit-hep/uhi/releases"
 [project.optional-dependencies]
 docs = [
   "sphinx>=4.0",
-  "sphinx-book-theme>=0.0.40",
+  "furo",
   "sphinx-copybutton>=0.3.1",
+  "myst-parser",
 ]
 test = [
   "pytest>=6",