NEWS
BiocBook 1.11.7
New features
enrich_llms_txt() names the Markdown copy of each page after the page,
<page>.md rather than quarto's <page>.llms.md, so that it lives at the
page's URL with .md in place of .html (e.g. pages/Chapter-2.md for
pages/Chapter-2.html). The links of llms.txt, and those between the
copies, follow.
- Every page of a book links to its Markdown copy: in its
<head>
(<link rel="alternate" type="text/markdown">), for AI assistants, and
under its title ("View as Markdown"), for readers. ?BiocBook-llms says how
to hide the latter.
- New books are created from template 1.1.3, whose
biocbook GitHub workflow
writes a .nojekyll file at the root of the book's GitHub Pages site.
Otherwise, GitHub Pages runs Jekyll, which renders every .md file into
an HTML page of the same name, colliding with the book's own pages. Books
created from an earlier template need the same change: in
.github/workflows/biocbook.yml, add touch llms-index/.nojekyll right
after mkdir -p llms-index.
BiocBook 1.11.6
Bug fixes
- New books are created from template 1.1.2, whose
biocbook GitHub
workflow no longer uses catchpoint/workflow-telemetry-action. Its
repository no longer exists, so every run failed before building
anything. Books created from an earlier template need the same change:
remove the "Collect Workflow Telemetry" step from
.github/workflows/biocbook.yml.
BiocBook 1.11.5
New features
setup_python() installs the pip: section of inst/requirements.yml,
with the environment's own pip, once its conda packages are in place.
Wheels from PyPI carry their compiled dependencies under names of their
own, so the python packages a book imports can no longer pick up a library
the R session has already loaded. On the Bioconductor builders, conda
builds of h5py (and so cooler) failed to import with
OPENSSL_3.2.0 not found, and matplotlib >= 3.11 with
undefined symbol: hb_ft_font_get_ft_face. ?BiocBook-python explains
which packages to declare under pip:, and which to keep under conda,
such as command-line tools.
setup_python() puts the command-line tools of the book's environment
(e.g. samtools) on the PATH from the first chunk on, rather than once
python has started.
llms.txt lists the packages of the pip: section after the conda
ones.
- New books are created from template 1.1.1, whose
inst/requirements.yml
declares the python packages a book imports under pip:, and keeps
conda for python itself and for command-line tools, rather than pinning
matplotlib below 3.11.
Bug fixes
setup_python() removes an environment whose build failed half way,
rather than re-using it on the next render.
BiocBook 1.11.4
New features
from_bookdown() converts a bookdown book in place, in its own
repository and on its current branch, rather than into a new repository.
Each step is a commit of its own, numbered [BiocBook 1/10],
[BiocBook 2/10]... (the package files, the pages moved to inst/ as they
are, the book settings, the removal of the bookdown build, the landing
page, cross-references, callouts, figure options, the setup of each page
and DESCRIPTION), with a short message, so that the conversion can be
reviewed step by step, and squashed or rebased like any other change. The
repository needs a first commit to convert on top of. package (by
default the book_filename of the book) replaces new_package, commit
replaces push, and user defaults to the owner of the origin remote.
from_bookdown() takes the licence of the book from a Creative Commons
licence its pages link to, or from its LICENSE file, and otherwise
writes the MIT licence of the template for the authors of the book.
Bug fixes
from_bookdown() only collapses the blank lines its rewrites create, and
keeps the final newline of a page, or its absence: the formatting of the
book is left alone.
MIGRATION.md is no longer committed, nor listed in .Rbuildignore: the
commits say what was done, and the file what is left to do, now including
the files that are not part of a BiocBook.
MIGRATION.md no longer claims that the output options it does not
translate have no quarto equivalent: for highlight, it gives the
highlight-style that keeps the code highlighting of the book.
BiocBook 1.11.3
New features
from_bookdown() migrates a bookdown book to a BiocBook in one call. It
creates the book package from the template, as init() does, and converts
the bookdown project into it: pages (with parts and appendices),
cross-references, figure layout options and msmbstyle question/solution
blocks, bibliographies, CSS and images, DESCRIPTION (title, authors,
dependencies), and the setup of the single R session bookdown renders
every chapter in. MIGRATION.md lists how often each rule was applied and
what still needs to be done by hand.
- The template's
biocbook GitHub workflow can be run manually on any branch:
it then builds the book against Bioconductor devel without pushing its
Docker image or deploying it, so that a branch can be checked before it
is merged. Deployments also index the llms.txt of every deployed version
of a book in docs/llms.txt.
Bug fixes
chapters() drops header attributes (e.g. {#sec-intro}) from chapter
titles.
- The template's question and answer callouts are styled again:
quarto
(>= 1.3) drops extra classes from callouts, so they are now wrapped in a
.callout-question or .callout-answer div.
- The template's
Dockerfile retries the quarto download on transient
errors (e.g. HTTP 503 from GitHub), which failed a book's build before
anything was installed.
- The template's
vignettes/Makefile is portable again: template 1.1.0
switched the llms profile on with GNU make extensions (:= and
$(shell ...)), which R CMD check reports as a warning in every book.
Documentation
?BiocBook-python and the template's requirements.yml explain why
matplotlib >= 3.11 cannot be imported on the Bioconductor images, and how
to pin it.
BiocBook 1.11.2
New features
- New books are created from template 1.1.0:
python chunks run through reticulate (python.reticulate: true), in
the conda environment declared in inst/requirements.yml, which now
uses the conda-forge and bioconda channels only and pins python;
- the book's
Docker image provisions that environment when a page runs
python, and receives GITHUB_PAT as a BuildKit secret, so that
GitHub-only dependencies no longer hit the API rate limit (#6);
- the
biocbook GitHub workflow uses the current major version of every
action (actions/upload-artifact@v3, which GitHub has rejected since
January 2025, made every new book's workflow fail), and can pin the
quarto version a book is built with;
- books serve an
llms.txt file for AI assistants (see below);
- PDF output is no longer configured.
enrich_llms_txt(): books built with quarto >= 1.11 serve /llms.txt
and a Markdown copy of every page, for AI assistants. Template 1.1.0
switches this on (through an llms quarto profile, only when the
installed quarto supports it), and runs enrich_llms_txt() after every
render to add the book package, its Docker image, its python
environment and its other versions to llms.txt. With an older quarto,
enrich_llms_txt() writes a minimal llms.txt listing the chapters.
python_envs() lists the conda environments setup_python() has cached
on a machine, and python_envs(remove = ...) deletes them.
add_python_chapter() declares BiocBook and reticulate in the book's
Suggests, and pins the new page to the knitr engine.
Bug fixes
setup_python() keys each conda environment on the contents of
requirements.yml (envs/<name>-<hash>). Editing the file now gives a new
environment, rather than silently re-using the existing one on machines
that already had it, and two books only share an environment when they
declare exactly the same thing.
BiocBook 1.11.1
New features
BiocBooks can execute python code: add_python_chapter() adds a page
whose python chunks run through reticulate, in a conda environment
that setup_python() creates from inst/requirements.yml while the book
builds, including on the Bioconductor builders.
micromamba() finds a micromamba binary, or downloads a pinned and
checksummed one, so that books can build their python environment on
machines without conda.
Bug fixes
add_chapter() and add_preamble() insert new pages under the
chapters: entry of _book.yml wherever it is, rather than assuming it
sits on the third line.