Merge pull request #260 from eccenca/feature/zensical-addons

Expose every tools script as a dec-tool subcommand

Author: rpietzsch

.pre-commit-config.yaml

@@ -11,8 +11,8 @@ repos:
         pass_filenames: false
 
       - id: nav-drift
-        name: check:nav
-        entry: task check:nav
+        name: check:navigation
+        entry: task check:navigation
         language: python
         pass_filenames: false
-        files: '(^docs/.*\.pages$|^nav\.yml$|^tools/build_nav\.py$)'
+        files: '(^docs/.*\.pages$|^nav\.yml$|^tools/build_navigation\.py$)'

README.md

@@ -48,24 +48,19 @@ check** - the build fails if any of it regresses:
 | `tablesort`, `glightbox` | vendored under `docs/assets/`; `tools/localize_bundle_assets.py` rewrites the CDN URLs Zensical bakes into its JS bundle |
 | Redirects | static stubs under `docs/` |
 | Comment opt-out | `overrides/partials/comments.html` |
-| Tag listings ([#38](https://github.com/zensical/backlog/issues/38)) | `tools/render_tag_listings.py` - **temporary**, see `tasks/spec.md` |
-| Tag chip links ([#38](https://github.com/zensical/backlog/issues/38)) | `overrides/partials/tags.html` - **temporary**, same removal trigger |
-
-The tag-listing renderer expands the `<!-- material/tags -->` markers on `/tags/` and
-`/tutorials/` after the build, and the `tags.html` override links each page's tag chips to
-its section there. Both are deliberately throwaway: the Markdown sources still use
-Material's own marker syntax and Zensical's stock template already knows how to render a
-linked chip - it just has no listing to point at yet. When Zensical ships listings the
-feature works natively, the renderer prints a banner telling you to delete it, and the
-override can go with it.
-
-The two build the anchor slug independently - MiniJinja in the template, Python in the
-renderer - so `check_zensical_output.py` asserts that every chip anchor resolves on
-`/tags/`. That check is what turns a slug mismatch into a failed build instead of 703 dead
-links.
-
-`task check:nav` additionally fails if `nav.yml` no longer matches the `docs/**/.pages`
-files, which remain the source of truth for navigation (`task nav` regenerates it).
+
+Tag listings and the links from each page's tag chips to them are **native** as of
+Zensical 0.0.58. The local stand-ins for both - a post-build renderer and a `tags.html`
+partial override - are gone; the Markdown sources still carry Material's own
+`<!-- material/tags -->` markers, which Zensical now expands itself.
+
+`check-zensical-output` keeps guarding the result: it asserts that tag chips link
+somewhere at all and that every anchor they point at exists on `/tags/`. A slug mismatch
+between a chip and its listing would otherwise ship as hundreds of dead links rather than
+fail the build.
+
+`task check:navigation` additionally fails if `nav.yml` no longer matches the `docs/**/.pages`
+files, which remain the source of truth for navigation (`task update:navigation` regenerates it).
 
 See `tasks/handoff.md` for the full migration notes.
 

Taskfile.yml

@@ -63,39 +63,22 @@ tasks:
     cmds:
       - task: check:links
       - task: check:rumdl
-      - task: check:nav
+      - task: check:navigation
       - task: check:output
 
-  check:nav:
+  check:navigation:
     desc: Fail if nav.yml is out of sync with the docs/**/.pages files
     deps:
       - install
     cmds:
-      - |
-        expected=$(mktemp)
-        trap 'rm -f "$expected"' EXIT
-        poetry run python tools/build_nav.py > "$expected"
-        if ! diff -u nav.yml "$expected"; then
-          echo
-          echo "nav.yml is out of date with respect to the docs/**/.pages files."
-          echo "Run 'task nav' and commit the result."
-          exit 1
-        fi
-        echo "nav.yml matches the .pages files."
+      - poetry run dec-tool build-navigation --check
 
   check:output:
     desc: Fail if a feature we reimplemented for Zensical regressed in the build
     deps:
       - build
     cmds:
-      - poetry run python tools/check_zensical_output.py site
-
-  nav:
-    desc: Regenerate nav.yml from the docs/**/.pages files
-    deps:
-      - install
-    cmds:
-      - poetry run python tools/build_nav.py > nav.yml
+      - poetry run dec-tool check-zensical-output
 
   check:links:
     desc: Check outgoing links
@@ -136,7 +119,7 @@ tasks:
       # Zensical bakes unpkg.com URLs into its JS bundle; rewrite them to the
       # vendored copies. Part of building, not of checking - without it the
       # published site issues third-party requests.
-      - poetry run python tools/localize_bundle_assets.py site
+      - poetry run dec-tool localize-bundle-assets
 
   serve:
     desc: Serve the page on localhost with live reload (no post-build steps)
@@ -265,6 +248,13 @@ tasks:
           PATHS: ./docs/build/integrations/index.md
         ignore_error: true
 
+  update:navigation:
+    desc: Regenerate nav.yml from the docs/**/.pages files
+    deps:
+      - install
+    cmds:
+      - poetry run dec-tool build-navigation
+
   public:versions:
     desc: List public documentation versions
     deps: