Gut-to-soil microbiome axis tutorial source 💩🌱

The built documentation can be found at https://gut-to-soil-tutorial.readthedocs.io/en/latest/.

Development instructions

The following sub-sections illustrate how to develop this documentation.

Create the development environment

To build this documentation locally for development purposes, first create your development environment.

cd gut-to-soil-tutorial
conda env create -n gut-to-soil-tutorial --file environment-files/readthedocs.yml
conda activate gut-to-soil-tutorial
q2doc refresh-cache

Build the book

Next, build the book:

make html

(Alternatively, make preview or make fast-preview can speed up test builds.)

Figures

The figures under docs/figures/ are MyST {figure} fragments, one per figure, that the tutorial page includes where the figure is first cited. They, and the image files beside them, are generated by @gregcaporaso's figures repository (make tutorial-figures there) and should not be edited by hand.

Each fragment currently references its image by absolute URL, https://raw.githubusercontent.com/qiime2/gut-to-soil-tutorial/<commit>/docs/figures/<slug>.<svg|png>, pinned to one commit of this repository, so a published build never changes under a later push. This is a workaround for a suspected mystmd bug. This tutorial is embedded in amplicon-docs ({embed} xref:gut-to-soil-target#gut-to-soil-16s-tutorial), and mystmd's embed transform rewrites an embedded page's links to the remote site but not its image paths, so a relative image path 404s on the embedding site, while an http(s) image is downloaded by every site that builds the page. The plan is to get the embed transform fixed in mystmd and then return the fragments to relative paths (figures/<slug>.<ext>), which is one variable (FIGURE_URL_BASE) in the figures repository's Makefile.

Until then, to update the figures: regenerate, commit and push the changed files, set the pinned commit (FIGURE_COMMIT in the figures repository's Makefile) to that pushed commit, regenerate again and commit the re-pointed fragments. After the fragments change and ReadTheDocs has rebuilt this site, amplicon-docs needs a rebuild of its own to pick up the new page data; nothing changes in that repository.

Serve the book locally

Finally, run the following to serve the built documentation locally:

make serve

Have fun!