1 Why Sphinx

Writing notes? You probably are using LaTeX. LaTeX's good, no doubt. But, what if I need multiple output format out of one source? So they say, USE PANDOC.

You know pandoc. It's fast, easy to use. But I want to generate everything with one command.

"Check out the Sphinx project!"

Alright it's not made for writing notes or thesis. But J Terrace did write a customized version (called sphinxtr) with everything you need for a thesis project, out of the box. However, the HTML theme is a little bit technical.

So I added bootstrap theme to sphinxtr. Checkout the source.

This is a Fork

This is a fork of sphinxtr. Almost everything is from there. I only added bootstrap theme and did a few adjustments.

Many thanks to the maintainers of these projects.

1.1 Installation and Usage

Basically just install everything in the requirements.txt:

pip install -r requirements.txt

Except that python-setuptools, python-virtualenv, texlive-full are to be installed first if you haven't.

The following part is GRABBED from installation guide for sphinxtr.
  1. Install Sphinx, which in turn requires Python. (I believe everyone installed python.)
  2. Setuptools (look for the most up to date version)
  3. Virtualenv
  4. Tex Live

Now create a virtualenv. This will help you to separate the requirements from this project from other Python projects you might have:

virtualenv venv
source ./venv/bin/activate

Note

You can get out of the virtualenv by either closing the terminal or by calling deactivate.

Then install the required Python packages:

pip install -r requirements.txt

To build the output with one line command, you need make. The following targets are supported:

html
Builds HTML format, separated into sections
singlehtml
Builds HTML format on a single page
text
Builds text files, separated into sections
singletext
Builds a single text file
latexpdf
Builds into latex source files and then compiles into a PDF. Requires latex.