feat(compile_formal_docs): mirror docs/ subtree so formal docs can embed assets#15
Open
abitofhelp wants to merge 2 commits into
Open
feat(compile_formal_docs): mirror docs/ subtree so formal docs can embed assets#15abitofhelp wants to merge 2 commits into
abitofhelp wants to merge 2 commits into
Conversation
…bed assets
adafmt#56 needs the SDS to embed architecture diagrams via
image("../diagrams/foo.svg"). The previous build copied .typ sources
flat into the temp directory, so any ../<dir>/ asset reference pointed
outside the Typst project root — typst rejected it with
"cannot read file outside of project root".
Fix: mirror the project's whole docs/ subtree into the temp build
(generated *.pdf excluded — build outputs, not inputs), overlay the
shared templates next to the mirrored .typ sources, and compile each
document with `--root` at the docs mirror. Cross-directory asset
references now resolve while #import "core.typ" (a same-directory
import) still works.
This is a general docs-asset solution: any asset under docs/ is
reachable, not just docs/diagrams/. No project-specific special case.
Tests: tests/test_compile_formal_docs.py — find_project_root, dry-run,
plain-doc compile (regression guard), embedded-diagram compile (the
adafmt#56 regression — fails pre-fix with the outside-root error),
and stale-PDF-in-docs tolerance. typst-dependent tests skip cleanly
when typst is absent. Full suite 139 passing.
Refs: adafmt#56
…chanics GPT PR #14 review suggested a non-typst test so the docs-mirror mechanics stay covered on runners without typst installed. Monkeypatches subprocess.run and asserts the compile command is rooted at the docs mirror, the .typ source is mirrored under <root>/formal/, and the sibling diagram asset is mirrored under <root>/diagrams/ at invocation time. Refs: adafmt#56
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
1 participant
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.
Summary
Merges the
compile_formal_docsfeature intohybrid_scripts_pythonmain.Two commits, dated 2026-05-15:
feat(compile_formal_docs): mirror thedocs/subtree so formal docs canembed asset files.
test(compile_formal_docs): typst-free check of--rootand the mirrormechanics.
Why this must be merged, not dropped
This branch was reviewed as a cleanup candidate. It is not disposable:
makefile/compile_formal_docs.pyis already referenced by thehybrid_lib_adaandhybrid_app_adaMakefiles and is present in theirscripts/python/sharedsubmodule checkouts.hybrid_scripts_pythonis theshared-submodule source repo for that script; leaving these commits only on
an unmerged branch means
mainlags the script its consumers already dependon. Merging brings
maininto sync with what the hybrid starters use.Scope
makefile/compile_formal_docs.py+tests/test_compile_formal_docs.pyonly.Shared-submodule source change — consumers pick it up on their next
git submodule update --remote.