Getting Started: Overview & Introduction to Concepts¶

Concepts¶

Sphinx Philosophy¶

Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.

reST -> Sphinx -> HTML

So as a user of Sphinx, your main job will be writing these text files. This means that you should be minimally familiar with reStructuredText as a language. It’s similar to Markdown in a lot of ways, if you are already familiar with Markdown.

Tasks¶

Installing Sphinx¶

The first step is installing Sphinx. Sphinx is a python project, so it can be installed like any other python library. Every Operating System should have Python pre-installed, so you should just have to run:

pip install sphinx

Note

Advanced users can install this in a virtualenv if they wish. Also, easy_install install Sphinx works fine if you don’t have pip.

Get this repo¶

To do this tutorial, you need the actual repository. It contains the example code that we will be documenting.

You can clone it here:

git clone https://github.com/ericholscher/djangocon-sphinx-tutorial

Getting Started¶

Now you are ready to start creating documentation. You should have a directory called crawler, which contains source code in it’s src directory. Inside the crawler you should create a docs directory, and move into it:

cd crawler
mkdir docs
cd docs

Then you can create the Sphinx project skeleton in this directory:

sphinx-quickstart

Have the Project name be Crawler, put in your own Author name, and put in 1.0 as the Project version. Otherwise you can accept the default options.

My output looks like this:

-> sphinx-quickstart
Welcome to the Sphinx 1.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: 

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: Crawler
> Author name(s): Eric Holscher

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]:

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: 
> Create Windows command file? (y/n) [y]: 

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Your file system should now look similar to this:

crawler
├── src
└── docs
    ├── index.rst
    ├── conf.py
    ├── Makefile
    ├── make.bat
    ├── _build
    ├── _static
    ├── _templates

We have a top-level docs directory in the main project directory. Inside of this is:

index.rst:: This is the index file for the documentation, or what lives at /. It normally contains a Table of Contents that will link to all other pages of the documentation.
conf.py:: Allows for customization of Sphinx. You won’t need to use this too much yet, but it’s good to be familiar with this file.
Makefile & make.bat:: This is the main interface for local development, and shouldn’t be changed.
_build:: The directory that your output files go into.
_static:: The directory to include all your static files, like images.
_templates:: Allows you to override Sphinx templates to customize look and feel.

Building docs¶

Let’s build our docs into HTML to see how it works. Simply run:

# Inside top-level docs/ directory.
make html

This should run Sphinx in your shell, and output HTML. At the end, it should say something about the documents being ready in _build/html. You can now open them in your browser by typing:

open _build/html/index.html

You can also view it by running a web server in that directory:

# Inside docs/_build/html directory.
python -m SimpleHTTPServer

Then open your browser to http://localhost:8000.

This should display a rendered HTML page that says Welcome to Crawler’s documentation! at the top.

Note

make html is the main way you will build HTML documentation locally. It is simply a wrapper around a more complex call to Sphinx, which you can see as the first line of output.

Custom Theme¶

You’ll notice your docs look a bit different than mine. You can change this by setting the html_theme setting in your conf.py. Go ahead and set it like this:

html_theme = 'sphinx_rtd_theme'

If you rebuild your documentation, you will see the new theme:

make html

Warning

Didn’t see your new theme? That’s because Sphinx is smart, and only rebuilds pages that have changed. It might have thought none of your pages changed, so it didn’t rebuild anything. Fix this by running a make clean html, which will force a full rebuild.

Extra Credit¶

Have some extra time left? Check out these other cool things you can do with Sphinx.

Understanding `conf.py`¶

Sphinx is quite configurable, which can be a bit overwhelming. However, the conf.py file is quite well docuemnted. You can read through it and get some ideas about what all it can do.

A few of the more useful settings are:

project
html_theme
extensions
exclude_patterns

This is all well documented in the Sphinx The build configuration file doc.

Moving on¶

Now it is time to move on to Step 1: Getting started with RST.