17. Appendix: How to build this book
Caution
This appendix is a work in progress.
This book is typeset using a light-weight markup language called
restructured text, a rather light-weight approach to markup where
you can see the formatting with text symbols, like ======
to make
titles, and *emphasize this*
to emphasize text. These resemble
the way you might arrange things in an old-style email.
The way we build restructured text files into our document for web presentation (or to make a PDF file or an epub file for ebook readers) is with the Sphinx tools. Sphinx was developed by the python community to allow the building of large-scale python documentation sites that describe software libraries, but it also works well for a book that is unrelated to code.
Within sphinx we use the “read the docs” (rtd) theme, and some extensions for things like bibliographies.
17.1. Installing the Sphinx tools
On a debian-based Linux distribution you should be able to run:
$ sudo apt install make python3-sphinx python3-sphinx-rtd-theme
$ sudo apt install python3-sphinxcontrib.bibtex
which will give you the tools you need to build the html output. To build the LaTeX output you will probably need these packages:
$ sudo apt install texlive-latex-base texlive-latex-recommended
$ sudo apt install texlive-fonts-recommended biber latexmk
$ sudo apt install librsvg2-bin pdf2svg
and more might be needed.
17.2. Building the book
To build the html, LaTeX, and epub versions you type the following:
$ make html
## output will be in build/html/index.html
$ make latexpdf
## output will be in latex/ResearchSkillsandCriticalThinking.pdf
$ make epub
## output will be in build/research-skills.epub