SpaDES.docs 0.5.0

Figures in a module chapter now survive being staged into a manual.

A module chapter is rendered from wherever the document lives: its own directory when the module renders alone, and the book root once prepManualRmds() has staged it into a manual. Its figures did not move with it, and modules worked around that with normPath(), which bakes in the path of the machine that built the book. That renders locally and then publishes dead links — the LandR manual has been serving src="/home/runner/work/.../figures/..." from every module chapter, unresolvable for every reader, with the build green throughout.

• stageFigure() returns a path that works in both cases: unchanged when the module renders alone, and when the chapter is staged, the figure is copied into a directory of the module's own beside the chapter, with the relative path to that copy returned. Per module, because modules reuse conventional names — every one writes figures/moduleVersionBadge.png, and a shared directory showed each chapter the badge of whichever module was knitted last. Use it where a chunk builds markdown by hand, such as a linked badge.
• includeFigure() is the chunk form, for knitr::include_graphics(). Passing a staged path to include_graphics() directly cannot work: it checks the file against the working directory — the module's — while the staged path is relative to the book root.
• prepManualRmds() copies the images a chapter references in prose in beside the staged chapter and rewrites the references, and turns caching off for any chunk that stages a figure. knitr serves a cached chunk's output without re-running its code, so the copy was skipped and, from the second build on, the chapter referenced a file that was never staged.

Verified by rendering a two-module book to HTML and PDF twice, the second build on a warm cache, checking each published image against its source.

SpaDES.docs 0.4.0

Support for manuals that publish a PDF of each release.

• publishManualArchive() copies a manual's archived release PDFs into the rendered book directory and writes an index page listing them, newest first. The index is built from the files actually present rather than a list kept by hand, and ordering uses numeric_version(), so v1.0.10 sorts above v1.0.2.

  The archived PDFs belong in version control rather than only on the published branch: that branch is rebuilt by every deploy, and an old PDF cannot be regenerated from current sources. Publishing them from a tracked directory also keeps the deploy an exact image of what was built, which is what stops stale files accumulating there.

• Building a continuously updated manual gains a Releases, and keeping the old PDFs section: taking the version from DESCRIPTION rather than the build script, archiving each release's PDF, publishing the archive with the site, linking it statically from the preface, and committing the new PDF from the workflow so a release does not depend on someone remembering a manual step.

SpaDES.docs 0.3.0

Six new exported functions, promoted out of the manuals that were carrying near-identical copies of them, and a warning for the one failure mode that was silent.

The manuals' shared build code, promoted

fireSenseManual and LandR-Manual had near-identical build scripts -- their install.R files were byte-identical apart from comment wording. Four of these encode a defect that actually broke a build, so the fix now lives in one place with a test rather than as a comment copied between repositories.

• collapseModuleBibs() merges the modules' references_*.bib files into the single bibliography bookdown wants, skipping files with no entries. A module that cites nothing yet ships a comments-only .bib, and RefManageR::ReadBib() fails on it -- enough to take down a whole manual over one placeholder.
• installModulePkgs() installs the packages a manual's modules declare, or with install = FALSE resolves the list without installing. It assigns the list before installing rather than piping it, because Require::Install() calls substitute() on its first parameter, so a piped expression asks the installer for a package literally called packages.
• stagePagesFiles() writes .nojekyll, and optionally CNAME, into the rendered book directory. A deploy publishes the contents of that directory, so these never reach the site if written to the repository root.
• archiveManualPDF() copies a rendered PDF to a versioned name, and does nothing when no PDF was produced. It also refuses an empty version, since Sys.getenv() of an unset variable is "" and would archive <name>-v.pdf over the previous build.
• manualPaths() resolves a manual's root, rendered book, citations and figures directories from _bookdown.yml. It errors rather than guessing when output_dir is unset, because guessing renders the book somewhere the deploy does not look.
• writePkgBib() and downloadCSL() cover the remaining boilerplate.

RefManageR, rprojroot and SpaDES.core are Suggests, guarded at runtime, so none becomes a hard dependency.

prepManualRmds()

Now warns in both directions. It already warned when _bookdown.yml listed a chapter that was not prepared; the reverse was dropped silently, so a prepared-but-unlisted chapter was written, built cleanly, and was simply absent from the book. That barely mattered while every manual took its modules from git submodules, and stops being safe once a manual takes its module list from somewhere else.

Documentation

The vignette is now two, split by how a manual treats its modules:

• Building a project manual -- pins them, so the manual agrees with the results it describes (LandWeb).
• Building a continuously updated manual -- tracks them, so a documentation fix reaches the published site on its own (fireSenseManual, LandR-Manual).

Both worked examples use the functions above.

Also

Re-documented with roxygen2 8.1.0, in its own commit: no .Rd changes, and the NAMESPACE directives are identical before and after.

SpaDES.docs 0.2.0

• new vignette, Building a project manual: the layout a manual uses, a runnable
  minimal example, what prepManualRmds() does to each module .Rmd and why,
  the build-script pattern, and the things that bite. Resolves the
  VignetteBuilder field that had been declared against no vignette (#2);
• the README says what the package is for, points at the vignette, and lists the
  manuals built with it. pkgdown builds the site home page from it, so it is also
  the front page of https://predictiveecology.github.io/SpaDES.docs/ (#3);
• Breaking: prepManualRmds() writes the generated chapters to a staging
  directory under the book root (stagingPath, default _manual_rmds) instead
  of into each module's own directory. Books must list the chapters from there
  in _bookdown.yml, and should add the directory to .gitignore. The module
  directories are git submodules in every project that uses this package: a
  failed build used to leave a <module>2.Rmd in each one, and each module
  repository carried a .gitignore line to hide it. Verified equivalent by
  rendering the same chapters from both locations -- the output is byte-identical,
  including relative images, cross-references and citations;
• chapters left by a previous run are cleared, so a module removed from a project
  no longer lingers as an orphan chapter;
• prepManualRmds() no longer fails when _bookdown.yml lists none of the
  modules under modulePath -- the case reported in #1, where the modules exist
  but every module line is commented out. It warns, writes the chapters, and
  skips the cross-chapter de-duplication it cannot do (#1);
• prepManualRmds() parses _bookdown.yml as YAML rather than by indentation.
  The old sub(" - ", ...) assumed exactly two spaces, could not read the
  flow-style rmd_files: [a, b] form, and counted a commented-out line as a
  listed chapter;
• prepManualRmds() gains argument bookdownYML, and checks the file exists
  before writing anything. A missing book file used to surface only after every
  <module>2.Rmd had been created, leaving them behind;

SpaDES.docs 0.1.0

• drop support for R 4.1 and 4.2;
• prepManualRmds() gains argument ignoreModules. It matches whole module
  names; as a regex alternation it also dropped modules whose names merely
  contained one, and character(0) dropped everything;
• prepManualRmds() classifies each line of a module .Rmd once -- YAML, chunk
  header, chunk body, prose -- and each rewrite now works from that instead of
  re-deriving document structure with its own regex. Fixes a family of failures:
  a prose mention of root.dir treated as a setting, ## References inside a
  sentence treated as a heading, and a (ref:key) use in mid-paragraph treated
  as a duplicate definition and deleted;
• prepManualRmds() no longer aborts on a module with no setup chunk; it
  synthesizes one. Five of the fireSense modules have none, and each would have
  stopped the whole book;
• prepManualRmds() no longer crashes de-duplicating text references. It
  removed lines and then kept indexing the shortened vector with the original
  line numbers;
• prepManualRmds() warns instead of continuing silently when _bookdown.yml
  lists chapters that were not prepared, and when there are no modules to prepare
  at all. Note this does not yet cover #1, where the modules exist but every
  module line in _bookdown.yml is commented out;
• rebuildCache reaches the generated chapter when a module mentions
  cache.rebuild only in a comment;
• prepManualRmds() no longer deletes a module's prose along with its YAML header. It removed
  every line from the first --- to the last, so a --- thematic rule anywhere in a module's
  documentation took the header and all prose above the rule with it, silently. Only the header
  is removed now, and only when nothing but whitespace precedes it -- the same way
  SpaDES.core::moduleRmdToVignette() reads the file;
• modelr is no longer a dependency; modelr::seq_range() was the call that caused the above;
• the package has a testthat suite;