Document PDF build process and add a script for it

develop
lethosor 2020-07-15 21:42:43 -04:00
parent ef53cac05b
commit 470456583c
4 changed files with 46 additions and 6 deletions

1
.gitignore vendored

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

@ -236,9 +236,9 @@ Running Sphinx manually
----------------------- -----------------------
You can also build the documentation without going through CMake, which may be 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 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 To build the documentation with default options, run the following command from
the root DFHack folder:: the root DFHack folder::
@ -248,6 +248,19 @@ the root DFHack folder::
Sphinx has many options to enable clean builds, parallel builds, logging, and Sphinx has many options to enable clean builds, parallel builds, logging, and
more - run ``sphinx-build --help`` for details. 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: .. _build-changelog:

@ -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" "$@"

@ -2,8 +2,11 @@
# usage: # 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 $(dirname "$0")
cd .. cd ..
@ -17,4 +20,4 @@ if [ -z "$JOBS" ]; then
JOBS=2 JOBS=2
fi 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" "$@"