Document PDF build process and add a script for it

.gitignore

@@ -17,6 +17,7 @@ build/VC2010
 # Sphinx generated documentation
 docs/_*
 docs/html/
+docs/pdf/
 
 # in-place build
 build/Makefile

docs/Documentation.rst

@@ -236,9 +236,9 @@ Running Sphinx manually
 -----------------------
 
 You can also build the documentation without going through CMake, which may be
-faster. There is a ``docs/build.sh`` script available for Linux and macOS that
+faster. There is a ``docs/build.sh`` script provided for Linux and macOS that
 will run essentially the same command that CMake runs - see the script for
-options.
+additional options.
 
 To build the documentation with default options, run the following command from
 the root DFHack folder::
@@ -248,6 +248,19 @@ the root DFHack folder::
 Sphinx has many options to enable clean builds, parallel builds, logging, and
 more - run ``sphinx-build --help`` for details.
 
+Building a PDF version
+----------------------
+
+ReadTheDocs automatically builds a PDF version of the documentation (available
+under the "Downloads" section when clicking on the release selector). If you
+want to build a PDF version locally, you will need ``pdflatex``, which is part
+of a TeX distribution. The following command will then build a PDF, located in
+``docs/pdf/latex/DFHack.pdf``, with default options::
+
+  sphinx-build -M latexpdf . ./docs/pdf
+
+There is a ``docs/build-pdf.sh`` script provided for Linux and macOS that runs
+this command for convenience - see the script for additional options.
 
 .. _build-changelog:
 

docs/build-pdf.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+# usage:
+#   ./build-pdf.sh
+#   SPHINX=/path/to/sphinx-build ./build-pdf.sh
+#   JOBS=3 ./build-pdf.sh ...
+# all command-line arguments are passed directly to sphinx-build - run
+# ``sphinx-build --help`` for a list, or see
+# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+
+cd $(dirname "$0")
+cd ..
+
+sphinx=sphinx-build
+if [ -n "$SPHINX" ]; then
+    sphinx=$SPHINX
+fi
+
+if [ -z "$JOBS" ]; then
+    JOBS=2
+fi
+
+"$sphinx" -M latexpdf . ./docs/pdf -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"

docs/build.sh

@@ -1,9 +1,12 @@
 #!/bin/sh
 
 # usage:
-# ./build.sh
+#   ./build.sh
-# ./build.sh sphinx-executable
+#   SPHINX=/path/to/sphinx-build ./build.sh
-# JOBS=3 ./build.sh ...
+#   JOBS=3 ./build.sh ...
+# all command-line arguments are passed directly to sphinx-build - run
+# ``sphinx-build --help`` for a list, or see
+# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
 
 cd $(dirname "$0")
 cd ..
@@ -17,4 +20,4 @@ if [ -z "$JOBS" ]; then
     JOBS=2
 fi
 
-"$sphinx" -a -E -b html . ./docs/html -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"
+"$sphinx" -a -b html . ./docs/html -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"