feat: use the SpaDES.docs 0.4.0 helpers - #172
Merged
Merged
Conversation
0.2.0 stages generated chapters under _manual_rmds/ instead of writing them into each module's own directory -- those are submodules, so a failed build used to dirty every one of them. build.R now calls the shared helpers rather than carrying its own copies. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
achubaty
force-pushed
the
feat/use-spades-docs-0.3.0
branch
from
September 18, 2026 16:40
9da8a8a to
00bd1b7
Compare
…uld not see CI failed on `git2r`: the P3M binary links `libgit2.so.1.7`, which ubuntu-latest does not install. Neither install-spatial-deps@v0.4 nor @main provides it, so add `libgit2-dev` alongside the other system deps. git2r cannot simply be dropped -- five module Rmds use it. Three problems this branch would otherwise introduce or leave in place: * **Deploying from `targets`.** Adding `targets` to the push trigger, while the deploy step is guarded only by `github.event_name != 'pull_request'`, means every push to a development branch publishes over the live GitHub Pages site -- with `clean: false`, so a later rebuild cannot fully undo it. Guard the deploy on `refs/heads/main`; `targets` still builds, which is the point of adding it to the trigger. * **A bibliography CI cannot assemble.** `references.bib` was both an input and the output, so the manual accumulated into its own bibliography. That works locally and silently drops every manual-only entry on a runner, where `citations/*` is gitignored and starts empty -- `ChubatyMcIntire2019`, cited by index.Rmd, is the one key no module bib supplies. Curated entries move to a tracked `citations/references_manual.bib`; `references.bib` becomes output-only. * **Archived PDFs never reaching the site.** `index.Rmd` links them as `archive/pdf/<file>`, relative to the published tree, and `docs/archive/pdf/` is tracked for that reason. The refactor dropped the copy into `docs/`, so the next version bump would 404. Restored -- and it now works, since `manualPaths()` fixed the `docs` path the old line resolved incorrectly. Also: cache `manual/_bookdown_files` too, since a render that ERRORS leaves LandWeb_manual.Rmd on disk and bookdown then stows the cache there rather than at the manual/ top level, so a failed build currently saves nothing for the retry; derive `ignoreModules` from the chapters `_bookdown.yml` lists instead of hand-maintaining a second copy (it yields HSI_Caribou_MB today, exactly as before); drop the three `library()` calls whose packages are now only used inside SpaDES.docs; clean up after prepManualRmds() at the path it reports rather than a hard-coded `_manual_rmds`; name the published figures directory so it is not confused with `paths$figures`, which is the source one; drop the duplicate `*_cache` ignore already covered by the root .gitignore; and record why install-spatial-deps is pinned to a branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
renv::restore() died before the manual was built:
unable to load shared object '.../igraph/libs/igraph.so':
libglpk.so.40: cannot open shared object file
Same first failure fireSenseManual hit.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CI failed twice in a row on the same shape of problem: a P3M binary installs cleanly, then
fails to LOAD minutes later on a missing shared object, naming only the .so. First git2r
on libgit2.so.1.7, then igraph on libglpk.so.40. Adding one apt package per failed run is
a four-minute round trip with no reason to believe the next one is the last -- burnSummaries
hit this before us and ended up hand-maintaining thirteen.
The cause is structural, not an oversight: `setup-renv` restores a lockfile and does not
resolve system requirements at all, unlike `setup-r-dependencies`, which delegates to pak
and installs them itself. PredictiveEcology/actions has no automatic resolution either --
`install-spatial-deps` is a fixed geospatial list, and `render-module-rmd`'s `extra-apt`
input documents why ("Modules have no DESCRIPTION, so nothing can derive their system
requirements automatically"). LandWeb, unlike a module, HAS a lockfile, so it can.
`.github/scripts/sysreqs.R` derives the list with `renv::sysreqs()` and writes it to a
file; the workflow installs it before `setup-renv` runs. 33 packages from 441 lockfile
entries, which covers both failures above.
It is derived PLUS curated, and deliberately so -- the gaps were measured against this
lockfile, not guessed:
* the database describes what a package needs to be BUILT, so it misses a library a
binary links but a source build vendors. That is exactly git2r: it resolves to
libssh2-1-dev while its binary wants libgit2.so.1.7.
* it is incomplete for some packages regardless: textshaping gets only libfreetype6-dev
(a source build also wants harfbuzz and fribidi), fs only cmake (fs 2.x also wants libuv).
* 39 of the 441 entries are GitHub sources it does not know at all.
So `EXTRA_SYSREQS` keeps six entries, each naming the package and the symptom, so a later
reader can tell a hand-added entry from a derived one and knows what to re-test before
dropping it.
Two things worth knowing about the script's shape, both found by running it rather than
reading it: `unlist()`ing a whole sysreqs entry yields "linux"/"ubuntu"/"debian" beside the
package names, so it takes `$packages` only; and renv writes its autoloader notice and a
backspace-rewritten [n/N] progress counter to STDOUT, which appends the first package name
to a line of junk -- so the list goes to a file, and every line is asserted to look like an
apt package name before it is written.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ild fails The PDF pass fails with `! Argument of \Gin@ii has an extra }` at line 1682 of LandWeb_manual.tex -- a line number in a file that no longer exists by the time the job ends, in a book whose chapters are staged by prepManualRmds() and whose figures are knitted. Neither the .tex nor the figure it references is reproducible from the sources alone, so there is currently no way to see which chapter or image produces the malformed \includegraphics without rebuilding the entire book elsewhere, on a toolchain that may not fail the same way. Three changes, all debugging-only: - `keep_tex: true` for bookdown::pdf_book, so rmarkdown's on.exit cleanup does not delete the .tex when the render errors; - `options(tinytex.clean = FALSE)` in the workflow's build step (not in build.R, so local builds keep their usual behaviour), because latexmk() otherwise removes LandWeb_manual.log -- the file its own error message tells you to read; - an `if: failure()` artefact upload carrying the .tex, the LaTeX logs, the staged chapters and the knitted figures. The upload runs only on failure and expires after 7 days, so a green build is unaffected. The two new build artefacts are gitignored. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The PDF pass has been failing with
! Argument of \Gin@ii has an extra }.
l.1682 ...bbcde9bf806da4952f84d8375e1935913.png}}}
The cause is in our own preamble, not in pandoc, bookdown or SpaDES.docs.
To make images inside links clickable under XeTeX, preamble.tex wrapped
\includegraphics using the classic delimited-parameter idiom:
\def\includegraphics#1#{\IncludeGraphicsAux{#1}}
`#1#` scans ahead to the first `{` and treats everything before it as the
star/optional argument. That holds only while the optional argument contains
no braces. pandoc 3 emits alt text as an option -- and CI now runs pandoc
3.8.3:
\includegraphics[keepaspectratio,alt={module-version-Badge}]{...png}
so the first `{` is the one opening `alt={`, the filename group is never seen
as the mandatory argument, and graphicx is handed a malformed argument.
\RenewDocumentCommand parses `s O{} m` properly, braces and all, and keeps the
XeTeXLinkBox wrapper, so image-link rendering is unchanged.
Verified by re-running xelatex over the .tex this build actually generated,
with only the preamble block swapped: the current preamble produces 10
`\Gin@ii` errors -- one per \includegraphics carrying `alt=`, 10 of the 24 in
the book -- and 90 cascading ones; the fixed preamble produces none.
Two things this was NOT, both checked and cleared: the `(ref:percent)`
duplicated-text-reference warning (real, but a separate cosmetic issue), and
rmarkdown's `--extract-media` (real -- 2.31 injects it for non-HTML output,
which is why these filenames are content SHA1s and why only the PDF pass is
affected -- but it explains the filename, not the failure).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Brings the branch onto the current dependency state so the manual build is
validated against what it will actually run on after merging, rather than the
toolchain it was debugged on.
The doc toolchain moved under this PR: rmarkdown 2.31 -> 2.32, bookdown
0.47 -> 0.48, knitr 1.51 -> 1.52, tinytex 0.60 -> 0.61, and terra 1.9-48
(GitHub) -> 1.9-50 (CRAN). rmarkdown 2.32 matters most here: it replaces the
blanket `--extract-media` it added for non-HTML output with a targeted
data-URI Lua filter, which is the mechanism that produced the SHA1-named PNGs
in the PDF pass. The \includegraphics fix in this branch is unaffected -- the
`alt={...}` option that breaks it comes from pandoc, not rmarkdown -- but the
extracted filenames should change, so the build is worth re-running.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rmarkdown 2.32 replaced the blanket `--extract-media` it used to add for
non-HTML output with a targeted data-URI filter. That flag had been copying
every referenced image into the book's media directory and rewriting the path,
which silently made module-relative image paths work.
Without it they stay relative -- and LaTeX resolves them against the BOOK ROOT,
not the module directory the chapter was staged from. Two chapters
(Biomass_speciesFactorial, NRV_summary) write the badge as a literal relative
markdown image:
[](http://commonmark.org)
so the PDF pass died with `! Unable to load picture or PDF file
'figures/markdownBadge.png'`. Every other image in the book already resolves to
an absolute path via Require::normPath(), and these two were the ONLY relative
paths in the generated .tex.
Shipping the badge at manual/figures/ satisfies both chapters with one file, and
keeps working for any future module chapter using the same conventional path.
This is not a regression from the \includegraphics fix in this branch -- that
one is confirmed working here: the generated .tex now has zero `\Gin@ii` errors
and zero SHA1-named extractions. It is a consequence of the rmarkdown update on
`targets`, which this branch merged in precisely so the manual would be built
against the toolchain it will actually run on.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…cs-0.3.0 # Conflicts: # .github/workflows/landweb-manual.yaml
0.4.0 adds publishManualArchive(), which replaces the hand-rolled copy of archive/ into docs/ and builds the version list from the PDFs actually published, so index.Rmd no longer keeps that list by hand. DESCRIPTION still pinned 0.0.1.9002 while renv.lock had moved on; both now name 0.4.0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
achubaty
changed the title
achubaty
marked this pull request as ready for review
September 21, 2026 20:49
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.
Draft: the manual has not been built on this branch, so CI here is the first
real test. Prepared in a temporary checkout — the local working copy is
mid-
tar_make()and was not touched.renv.lockis not part of this PR: the SpaDES.docs 0.3.0 pin was pushed totargetsseparately, and this branch is rebased onto it.Before that pin, SpaDES.docs was at 0.0.1.9002, which predates the change that
stages generated chapters under
_manual_rmds/. So this is that migration.manual/_bookdown.yml: 10 chapters now_manual_rmds/<M>2.Rmdmanual/build.Ruses the helpersmanualPaths(),writePkgBib(),downloadCSL(),collapseModuleBibs(),stagePagesFiles(),archiveManualPDF().nojekyllnow written insidedocs/read.dcf(...)[4]wasVersiononly because it was the fourth fieldmanual/.gitignore:_manual_rmds/,LandWeb_manual_cache/targetsmainonly, so a PR against this branch got no CI at allinstall-spatial-deps@v0.4->@mainmanual/*_cache,manual/*_filesmanual/_bookdown_filesdoes not exist, so the cache step saved nothing and warned every buildcheckout@v4->@v7,cache@v4->@v6r-version: 4.5.1->4.6.1renv.lockrecords 4.6.1, sosetup-renvwas restoring a lockfile built for a different ROne thing to confirm
HSI_Caribou_MBhas a module directory and ships an.Rmd, but no chapter in_bookdown.yml. Under 0.3.0 that means it is prepared and then silently left outof the book, which the new
prepManualRmds()warning reports on every build. Itis passed to
ignoreModuleshere, preserving today's output exactly. If itshould be documented, add a chapter and drop it from that argument.
🤖 Generated with Claude Code