chore: enhance development tooling and documentation

- Rewrite gen-init.sh to use tangerine for better template management
- Improve TOML linting with tombi support and better formatting
- Add numerous Python documentation inventory references
- Add tangerine template markers to __init__.py files

Author: liblaf

.cspell.json

@@ -46,6 +46,7 @@
     "scrapy",
     "sdist",
     "strftime",
+    "tombi",
     "trimesh",
     "unshallow",
     "venv",

template/.config/copier/mise/tasks/gen-init.sh

@@ -5,21 +5,36 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-CODE="import lazy_loader as lazy
+function has() {
+  type "$@" &> /dev/null
+}
 
-__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)"
-N_LINES=$(echo "$CODE" | wc --lines)
+TEMPLATE="\
+# tangerine-start: lazy-loader.py.jinja
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)
+# tangerine-end
+"
 
 git_root=$(git rev-parse --show-toplevel)
-readarray -t files < <(fd --fixed-strings --type file '__init__.pyi' "$git_root/src/")
-for file in "${files[@]}"; do
-  file="${file/%".pyi"/".py"}"
-  if [[ ! -f $file ]]; then
-    echo "$CODE" > "$file"
-    continue
-  fi
-  last_lines=$(tail --lines="$N_LINES" "$file")
-  if ! diff <(echo "$last_lines") <(echo "$CODE") &> /dev/null; then
-    echo "$CODE" >> "$file"
-  fi
-done
+src_dir="$git_root/src"
+if [[ -d $src_dir ]]; then
+  find "$src_dir" -name '__init__.pyi' -type f -print0 |
+    while IFS= read -d '' -r file; do
+      file="${file/%'.pyi'/'.py'}"
+      if has tangerine; then
+        if [[ ! -f $file ]]; then
+          tangerine <<< "$TEMPLATE" > "$file"
+        else
+          tangerine "$file"
+        fi
+      else
+        if [[ ! -f $file ]]; then
+          echo -n "$TEMPLATE" > "$file"
+        else
+          : # skip existing files
+        fi
+      fi
+    done
+fi

template/.config/copier/mise/tasks/lint-toml.sh

@@ -5,4 +5,22 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-sort-toml .ruff.toml pyproject.toml
+function has() {
+  type "$@" &> /dev/null
+}
+
+function pretty-toml() {
+  if has toml-sort; then
+    toml-sort --in-place --all "$@"
+    sed --expression='s/# :schema /#:schema /g' --in-place "$@"
+  fi
+  if has tombi; then
+    tombi format "$@"
+  fi
+}
+
+pretty-toml .ruff.toml pyproject.toml
+
+if has tombi; then
+  tombi lint
+fi

template/.config/copier/mkdocs.yaml.jinja

@@ -114,7 +114,50 @@ plugins:
     handlers:
       python:
         inventories:
+          - https://autoregistry.readthedocs.io/en/stable/objects.inv
+          - https://beartype.github.io/plum/objects.inv
+          - https://beartype.readthedocs.io/en/stable/objects.inv
+          - https://cherries.readthedocs.io/en/stable/objects.inv
+          - https://chex.readthedocs.io/en/stable/objects.inv
+          - https://cyclopts.readthedocs.io/en/stable/objects.inv
+          - https://docs.jax.dev/en/latest/objects.inv
+          - https://docs.kidger.site/equinox/objects.inv
+          - https://docs.kidger.site/jaxtyping/objects.inv
+          - https://docs.kidger.site/wadler_lindig/objects.inv
+          - https://docs.pola.rs/api/python/stable/objects.inv
+          - https://docs.pydantic.dev/latest/objects.inv
           - https://docs.python.org/3/objects.inv
+          - https://docs.pytorch.org/docs/stable/objects.inv
+          - https://docs.pyvista.org/objects.inv
+          - https://einops.rocks/objects.inv
+          - https://etils.readthedocs.io/en/stable/objects.inv
+          - https://felupe.readthedocs.io/en/stable/objects.inv
+          - https://gitpython.readthedocs.io/en/stable/objects.inv
+          - https://glom.readthedocs.io/en/stable/objects.inv
+          - https://grantjenks.com/docs/sortedcollections/objects.inv
+          - https://grantjenks.com/docs/sortedcontainers/objects.inv
+          - https://ipctk.xyz/objects.inv
+          - https://jcristharif.com/msgspec/objects.inv
+          - https://jinja.palletsprojects.com/en/stable/objects.inv
+          - https://joblib.readthedocs.io/en/stable/objects.inv
+          - https://liblaf-apple.readthedocs.io/en/stable/objects.inv
+          - https://liblaf-grapes.readthedocs.io/en/stable/objects.inv
+          - https://loguru.readthedocs.io/en/stable/objects.inv
+          - https://matplotlib.org/stable/objects.inv
+          - https://melon.readthedocs.io/en/stable/objects.inv
+          - https://networkx.org/documentation/stable/objects.inv
+          - https://numpy.org/doc/stable/objects.inv
+          - https://nvidia.github.io/warp/objects.inv
+          - https://platformdirs.readthedocs.io/en/stable/objects.inv
+          - https://pydicom.github.io/pydicom/stable/objects.inv
+          - https://pymeshfix.pyvista.org/objects.inv
+          - https://pytorch3d.readthedocs.io/en/latest/objects.inv
+          - https://rich.readthedocs.io/en/stable/objects.inv
+          - https://toolz.readthedocs.io/en/stable/objects.inv
+          - https://trimesh.org/objects.inv
+          - https://typing-extensions.readthedocs.io/en/stable/objects.inv
+          - https://wrapt.readthedocs.io/en/latest/objects.inv
+          - https://www.attrs.org/en/stable/objects.inv
         options:
           # General
           backlinks: tree

template/src/{{ package_dir }}/__init__.py

@@ -1,3 +1,5 @@
+# tangerine-start: lazy-loader.py.jinja
 import lazy_loader as lazy
 
 __getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)
+# tangerine-end