Improve documentation about build process (#238)

* Improve documentation about build process

* Additional rephrasing

* Updates per dhimmel review

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
 ```

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
+```