From 470456583c2b605f21e9be3c8b3fcc9e79dacab0 Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 15 Jul 2020 21:42:43 -0400 Subject: [PATCH] Document PDF build process and add a script for it --- .gitignore | 1 + docs/Documentation.rst | 17 +++++++++++++++-- docs/build-pdf.sh | 23 +++++++++++++++++++++++ docs/build.sh | 11 +++++++---- 4 files changed, 46 insertions(+), 6 deletions(-) create mode 100755 docs/build-pdf.sh diff --git a/.gitignore b/.gitignore index db4ed747c..9ff16b94c 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ build/VC2010 # Sphinx generated documentation docs/_* docs/html/ +docs/pdf/ # in-place build build/Makefile diff --git a/docs/Documentation.rst b/docs/Documentation.rst index 462932b0f..37fcc6ee6 100644 --- a/docs/Documentation.rst +++ b/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: diff --git a/docs/build-pdf.sh b/docs/build-pdf.sh new file mode 100755 index 000000000..76908b49b --- /dev/null +++ b/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" "$@" diff --git a/docs/build.sh b/docs/build.sh index 48e1bfd4a..95a97e539 100755 --- a/docs/build.sh +++ b/docs/build.sh @@ -1,9 +1,12 @@ #!/bin/sh # usage: -# ./build.sh -# ./build.sh sphinx-executable -# JOBS=3 ./build.sh ... +# ./build.sh +# 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" "$@"