Add opt-in `docs` dev-shell with `d2`

Factor the shared dev-shell toolchain into `basePkgs` + `baseHook`
so extra-tooling shells can extend it, then add a `docs` shell =
base + `pkgs.d2` (the diagram renderer our `.. d2::` sphinx
directive shells out to). Keeps `d2` OUT of the `default` shell so
casual dev envs stay lean.

Enter with `nix develop .#docs`, then build via `uv run --group
docs make -C docs html`.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

flake.nix

@@ -25,43 +25,63 @@
           cpython = "python313";
           venv_dir = "py313";
           pypkgs = pkgs."${cpython}Packages";
+
+          # shared base toolchain for every dev-shell variant;
+          # extra-tooling shells (eg. `docs`, below) extend it
+          # so heavy/niche deps stay OUT of the `default` shell.
+          basePkgs = [
+            # XXX, ensure sh completions activate!
+            pkgs.bashInteractive
+            pkgs.bash-completion
+
+            # XXX, on nix(os), use pkgs version to avoid
+            # build/sys-sh-integration issues
+            pkgs.ruff
+
+            pkgs.uv
+            pkgs.${cpython}# ?TODO^ how to set from `cpython` above?
+          ];
+
+          baseHook = ''
+            # unmask to debug **this** dev-shell-hook
+            # set -e
+
+            # link-in c++ stdlib for various AOT-ext-pkgs (numpy, etc.)
+            LD_LIBRARY_PATH="${pkgs.stdenv.cc.cc.lib}/lib:$LD_LIBRARY_PATH"
+
+            export LD_LIBRARY_PATH
+
+            # RUNTIME-SETTINGS
+            # ------ uv ------
+            # - always use the ./py313/ venv-subdir
+            # - sync env with all extras
+            export UV_PROJECT_ENVIRONMENT=${venv_dir}
+            uv sync --dev --all-extras
+
+            # ------ TIPS ------
+            # NOTE, to launch the py-venv installed `xonsh` (like @goodboy)
+            # run the `nix develop` cmd with,
+            # >> nix develop -c uv run xonsh
+          '';
         in
         {
           default = pkgs.mkShell {
+            packages = basePkgs;
+            shellHook = baseHook;
+          };
 
-            packages = [
+          # OPT-IN docs shell: `default` + the `d2` diagram
-              # XXX, ensure sh completions activate!
+          # renderer, kept OUT of `default` so casual dev shells
-              pkgs.bashInteractive
+          # don't pull it in. Enter with,
-              pkgs.bash-completion
+          #   >> nix develop .#docs
-
+          # then build (the `.. d2::` directive auto-detects the
-              # XXX, on nix(os), use pkgs version to avoid
+          # `d2` bin now on PATH; see `docs/_ext/d2diagrams.py`),
-              # build/sys-sh-integration issues
+          #   >> uv run --group docs make -C docs html
-              pkgs.ruff
+          docs = pkgs.mkShell {
-
+            packages = basePkgs ++ [ pkgs.d2 ];
-              pkgs.uv
+            shellHook = baseHook + ''
-              pkgs.${cpython}# ?TODO^ how to set from `cpython` above?
+              echo "[docs] d2 $(d2 --version) on PATH \
-            ];
+              — build via: uv run --group docs make -C docs html"
-
-            shellHook = ''
-              # unmask to debug **this** dev-shell-hook
-              # set -e
-
-              # link-in c++ stdlib for various AOT-ext-pkgs (numpy, etc.)
-              LD_LIBRARY_PATH="${pkgs.stdenv.cc.cc.lib}/lib:$LD_LIBRARY_PATH"
-
-              export LD_LIBRARY_PATH
-
-              # RUNTIME-SETTINGS
-              # ------ uv ------
-              # - always use the ./py313/ venv-subdir
-              # - sync env with all extras
-              export UV_PROJECT_ENVIRONMENT=${venv_dir}
-              uv sync --dev --all-extras
-
-              # ------ TIPS ------
-              # NOTE, to launch the py-venv installed `xonsh` (like @goodboy)
-              # run the `nix develop` cmd with,
-              # >> nix develop -c uv run xonsh
             '';
           };
         }