From ed4158c9f2a1b300f82d058be9aefe1f5eb72763 Mon Sep 17 00:00:00 2001 From: Anthony Gitter Date: Fri, 28 Jun 2019 16:50:04 -0500 Subject: [PATCH] Improve documentation about build process (#238) * Improve documentation about build process * Additional rephrasing * Updates per dhimmel review --- README.md | 12 ++++++++---- build/README.md | 15 ++++++++++++++- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c0e952b8..18208fb7 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The directories are as follows: + [`content`](content) contains the manuscript source, which includes markdown files as well as inputs for citations and references. See [`USAGE.md`](USAGE.md) for more information. -+ [`output`](output) contains the outputs (generated files) from the manubot including the resulting manuscripts. ++ [`output`](output) contains the outputs (generated files) from Manubot including the resulting manuscripts. You should not edit these files manually, because they will get overwritten. + [`webpage`](webpage) is a directory meant to be rendered as a static webpage for viewing the HTML manuscript. + [`build`](build) contains commands and tools for building the manuscript. @@ -40,8 +40,9 @@ The directories are as follows: ### Local execution -To run the Manubot locally, install the [conda](https://conda.io) environment as described in [`build`](build). -Then, you can build the manuscript on POSIX systems by running the following commands. +The easiest way to run Manubot is to use [continuous integration](#continuous-integration) to rebuild the manuscript when the content changes. +If you want to build a Manubot manuscript locally, install the [conda](https://conda.io) environment as described in [`build`](build). +Then, you can build the manuscript on POSIX systems by running the following commands from this root directory. ```sh # Activate the manubot conda environment (assumes conda version >= 4.4) @@ -52,11 +53,14 @@ bash build/build.sh # At this point, the HTML & PDF outputs will have been created. The remaining # commands are for serving the webpage to view the HTML manuscript locally. +# This is required to view local images in the HTML output. # Configure the webpage directory python build/webpage.py -# View the manuscript locally at http://localhost:8000/ +# You can now open the manuscript webpage/index.html in a web browser. +# Alternatively, open a local webserver at http://localhost:8000/ with the +# following commands. cd webpage python -m http.server ``` diff --git a/build/README.md b/build/README.md index 7749a6ac..1a886f1d 100644 --- a/build/README.md +++ b/build/README.md @@ -17,7 +17,7 @@ Please reference [Pull Request #40](https://github.com/manubot/rootstock/pull/40 Note: currently, **Windows is not supported**. -Install or update the [conda](https://conda.io) environment specified in [`environment.yml`](environment.yml) by running: +Install or update the [conda](https://conda.io) environment specified in [`environment.yml`](environment.yml) by running the following commands from this directory: ```sh # If the manubot environment already exists, remove it first @@ -33,3 +33,16 @@ However, it will fail on Windows due to the [`pango`](https://anaconda.org/conda 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](https://www.athenapdf.com/) [Docker image](https://hub.docker.com/r/arachnysdocker/athenapdf) to build the PDF. +Otherwise, `build.sh` uses [WeasyPrint](https://weasyprint.org/) 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 +```