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
docs/_*
docs/html/
docs/pdf/
# in-place build
build/Makefile

@ -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:

@ -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:
# ./build.sh
# ./build.sh sphinx-executable
# SPHINX=/path/to/sphinx-build ./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" "$@"