WIP: Feature/zensical - #259
Open
rpietzsch wants to merge 43 commits into
Open
Conversation
add package lifecycle
# Conflicts: # Taskfile.yml
re-enable `watch` as reload loop was fixed in that version.
add script building explicit `nav.yml` from `.pages` files wire `nav.yml` into config (`INHERIT`)
# Conflicts: # docs/automate/cmemc-command-line-interface/command-reference/package/index.md # docs/develop/.pages # poetry.lock
Dependencies - drop the private mkdocs-material-insiders fork for public mkdocs-material 9.7.x; removes the ACCESS_TOKEN secret and SSH key from CI and gitpod - drop Pillow and CairoSVG (social-card only) and the cairo apt step - pin zensical 0.0.57 with a note that the caret pin is deliberately narrow Features zensical does not implement, now handled here - self-host Roboto and Roboto Mono; theme.font: false stops the requests to fonts.googleapis.com and fonts.gstatic.com on every page - vendor tablesort, and glightbox, which zensical lazy-loads from unpkg at runtime on the image pages; tools/localize_bundle_assets.py rewrites the URLs baked into its JS bundle and fails on any new third-party host - replace mkdocs-redirects with static stubs for /cmemc/ and /explore-and-author/building-a-customized-user-interface/ - replace the meta plugin: comments default on, three pages opt out - drop the autolinks, privacy, meta and redirects plugin entries; keep social, tags and git-revision-date-localized so they resume when zensical maps them Rendering and navigation - drop the `extra` markdown extension: it bundles fenced_code, which competes with pymdownx.superfences for the ``` syntax. The winner depends on hash ordering, so roughly two thirds of builds mis-parsed `title="..."` fences and swallowed the following headings as raw text. Its other members are listed individually. See zensical/zensical#641. - build_nav.py: resolve a directory to its index.md and discover directories without a .pages file. Bare directory targets were never resolved to a page, costing those entries their icon and leaving the pages with no active nav position, which rendered the whole sidebar empty under navigation.tabs. It also restores 34 pages that were reachable on main but had no nav entry here. - override partials/tabs-item.html: zensical's version renders no icon, so the section icons never reached the tab bar - restore the Load Balancer tag icon with a neutral glyph; the Simple Icons AWS mark was removed upstream Guard rails - tools/check_zensical_output.py fails the build on a regression in anything we reimplemented, and reports social cards, tag listings and revision dates as PEND until zensical ships them - task check:nav fails if nav.yml drifts from the .pages files; also a pre-commit hook - both wired into task check and the CI workflows Social cards, tag listings and revision dates remain missing; see README.md.
…extra`: markdown.extensions.extra bundles fenced_code, which superfences is documented to replace. Enabling both is unsupported and left their precedence to hash ordering, so builds randomly mis-parsed `title="..."` fences and swallowed the following headings as raw text. Adds betterem, which fixes inverted emphasis on 4 pages. See zensical/zensical#882.
# Conflicts: # Taskfile.yml # poetry.lock
use native tag renderer (removed custom temp solution)
patch di reference template to render empty tag lists ("[]") instead of null ("")
The task regenerates nav.yml from the docs/**/.pages files, which puts it in the same family as update:cmemc, update:icons and the other regeneration tasks. Rename it accordingly and move it next to them, and update the two places that referenced the old name: the hint printed by check:nav and the navigation section of the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Three scripts were still invoked as `poetry run python tools/<script>.py` while the other three had long been click commands on the dec-tool group. Wire the remaining ones up the same way, following the conventions the existing commands already established: named options with repo-relative defaults and show_default, the command writing its own output, and progress on stdout via click.echo. build-navigation --docs-dir docs, -o nav.yml, --check check-zensical-output --site-dir site localize-bundle-assets --site-dir site build_nav.py becomes build_navigation.py so that file and command agree, as they do for the other five. The __main__ blocks are gone: dec-tool is now the only entry point. --check is new. It compares the generated navigation against whatever -o points at instead of writing it, prints a unified diff and exits 1 on drift, which replaces the mktemp/trap/diff shell block in check:nav - renamed to check:navigation to match update:navigation. The pre-commit nav-drift hook follows both the task rename and the module rename. Verified with `task check` (all four stages, including a full build) and `pytest -m "not integration"`; `task update:navigation` regenerates nav.yml byte-identically. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Bumping to Zensical 0.0.58 removed tools/render_tag_listings.py, the overrides/partials/tags.html partial and their tests, but left the README describing both as features "reimplemented here" - it pointed at two files that no longer exist. Tag listings and tag chip links are native now, so say that instead, and keep the paragraph on what check-zensical-output still guards: chips must link somewhere, and their anchors must exist on /tags/. The failure text of that very check named the deleted partial, which is the worst possible moment to read a stale hint. It now asks about Zensical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
The builder had two tests, both on the click layer, while the logic that actually derives the navigation was unpinned. That logic carries the subtle rules: dir_title capitalises only all-lowercase names, which is what keeps "link-IDS-event-to-KG" from becoming "Link Ids Event To Kg", and expand_dir walks a directory that has no .pages instead of emitting a bare reference - a fix whose 12-line comment explains that bare references empty the sidebar under navigation.tabs and drop pages from the navigation entirely. Adds coverage for dir_title, read_pages, has_markdown, discover_dir's MkDocs-like ordering, expand_dir, expand_item, build_nav_list and render_nav's two error paths, plus the CLI cases that were missing: --check against a not-yet-existing file, and a --docs-dir that is not there. Checked that the tests can fail: making dir_title capitalise unconditionally breaks the acronym case, and reverting expand_dir to a bare directory reference breaks five. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Expose every tools script as a dec-tool subcommand
Test Results1 files 2 suites 0s ⏱️ For more details on these failures, see this check. Results for commit 7b0e371. ♻️ This comment has been updated with latest results. |
Restores the old sidebar behavior (e.g. release notes showing the current version as its own entry) lost when nav.yml generation collapsed single-index-page directories into flat links.
mike deploy builds and commits in one process, with no hook in between, so its bare `zensical build` would publish the unpkg.com URLs localize-bundle-assets removes. Build here instead; mike still owns versions.json, aliases, redirect.
Zensical publishing: mike fork, publish task, preview
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.