docs(build): stage English sources with per-file rules so one make rebuilds - #4358
Merged
Merged
Conversation
…builds Fixes LinuxCNC#4354. After a full HTML docs build, touching a source under docs/src did nothing on the next `make`; only the run after that re-rendered the page. English sources are staged into docs/build/adoc/en by a bulk find|tar behind `.stage-en-stamp`, with the staged copies attached to it order-only. make stats a prerequisite once per run and re-stats it only if it decided to remake it, and an order-only edge never triggers a remake, so the staged .adoc kept its pre-staging mtime for the whole run. The stamp rewrote that same file mid-run, but the renderer had already compared the .html against the stale mtime and concluded it was up to date. Replace the stamp with one copy rule per staged file, so make knows the staged copy changed. cp -p also keeps the source mtime to the nanosecond where tar rounded it down to the whole second. Per-file rules alone would stage only what some rule asks for, which is a smaller set than the bulk copy produced, so a `stage-en` aggregate keeps the old guarantee that everything lands before anything renders; without it a partial like hal/halshow.adoc never arrives and the page including it renders an "Unresolved directive" placeholder.
Contributor
|
Works as expected. 👍 |
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.
Fixes #4354.
@BsAtHome I reproduced your recipe exactly: after a full HTML build,
touch ../docs/src/config/python-interface.adocthenmakere-stages the file but renders nothing, and only the run after that rebuilds the page.The cause is mine, from c774b79. English sources are staged into
docs/build/adoc/enby a bulkfind|tarbehind.stage-en-stamp, with the staged copies attached to it order-only:make stats a prerequisite once per run and re-stats it only if it decided to remake it. An order-only edge never triggers a remake, so that empty-recipe rule was never "remade" and the staged
.adockept its pre-staging mtime for the whole run. The stamp recipe rewrote that same file mid-run, but the renderer had already compared the.htmlagainst the stale mtime and concluded it was up to date. The nextmakesaw the fresh mtime and rendered.Replacing the stamp with one copy rule per staged file makes the change visible to make, so the render fires in the same run.
cp -palso keeps the source mtime to the nanosecond, wheretarrounded it down to the whole second; that could leave a staged copy a fraction older than a.htmlrendered from it in the same second and lose the edit outright.Per-file rules alone are not enough: they stage only what some rule asks for, which is a smaller set than the bulk copy produced. asciidoctor resolves
include::andimage:against the staged tree at render time and most of those are not make prerequisites, so a partial likehal/halshow.adocwould never land andhal/tutorial.htmlwould render an "Unresolved directive" placeholder instead of its content. Astage-enaggregate keeps the old guarantee.Verified with HTML, PDF and the seven translations enabled: a clean build renders 5210 pages and 32 Master PDFs with no unresolved directives, the two builds after it do no work, and a touched source re-renders in a single
makefollowed by a no-op.Could you confirm this clears it on your machine?
One note for later: while tracking this down I found that
docs/src/asciidepsstill strips a.txtsuffix from when the docs were written in that format, so since the move to.adocevery rule it generates names a target nothing builds and the whole dependency extractor has been inert. Editing a chapter has not rebuilt the Master PDF that includes it. I have that fixed and verified on a follow-up branch, which I will open once this merges, since the two touch adjacent rules in the same file.