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

Installing the Sphinx tools
===========================

On a debian-based Linux distribution you should be able to run:

.. code-block:: console

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

.. code-block:: console

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


Building the book
=================

To build the html, LaTeX, and epub versions you type the following:

.. code-block:: console

   $ 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