build

Building the manuscript

build.sh builds the repository. bash build/build.sh should be executed from the root directory of the repository. By default, build.sh creates HTML and PDF outputs. However, setting the BUILD_PDF environment variable to false will suppress PDF output. For example, run local builds using the command BUILD_PDF=false bash build/build.sh.

To build a DOCX file of the manuscript, set the BUILD_DOCX environment variable to true. For example, use the command BUILD_DOCX=true bash build/build.sh. To export DOCX for all CI builds, set an environment variable (see docs for GitHub Actions). Currently, equation numbers via pandoc-eqnos are not supported for DOCX output.

Format conversion is done using Pandoc. build.sh calls pandoc commands using the options specified in pandoc/defaults. Each file specifies a set of pandoc --defaults options for a given format. To change the options, either edit the YAML files directly or add additional --defaults files.

Environment

Note: currently, Windows is not supported.

Install the conda environment specified in environment.yml by running the following commands (from the repository's root directory):

# Install the environment
conda env create --file build/environment.yml

If the manubot environment is already installed, but needs to be updated to reflect changes to environment.yml, use one of the following options:

# option 1: update the existing environment.
conda env update --file build/environment.yml

# option 2: remove and reinstall the manubot environment.
# Slower than option 1, but guarantees a fresh environment.
conda env remove --name manubot
conda env create --file build/environment.yml

Activate with conda activate manubot (assumes conda version of at least 4.4). The environment should successfully install on both Linux and macOS. However, it will fail on Windows due to the pango dependency.

Because the build process is dependent on having the appropriate version of the manubot Python package, it is necessary to use the version specified in environment.yml. The latest manubot release on PyPI may not be compatible with the latest version of this rootstock repository.

Building PDFs

If Docker is available, build.sh uses the Athena Docker image to build the PDF. Otherwise, build.sh uses WeasyPrint to build the PDF. It is common for WeasyPrint to generate many warnings and errors that can be safely ignored. Examples are shown below:

WARNING: Ignored `pointer-events: none` at 3:16, unknown property.
WARNING: Ignored `font-display:auto` at 1:53114, descriptor not supported.
ERROR: Failed to load font at "https://use.fontawesome.com/releases/v5.7.2/webfonts/fa-brands-400.eot#iefix"
WARNING: Expected a media type, got only/**/screen