18. 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.

18.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.

18.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