Getting Started: Overview & Introduction to Concepts¶
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.
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
Advanced users can install this in a virtualenv if they wish.
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
Now you are ready to start creating documentation.
You should have a directory called
which contains source code in it’s
crawler you should create a
and move into it:
cd crawler mkdir docs cd docs
Then you can create the Sphinx project skeleton in this directory:
Have the Project name be
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:
- 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.
- 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.
- This is the main interface for local development, and shouldn’t be changed.
- The directory that your output files go into.
- The directory to include all your static files, like images.
- Allows you to override Sphinx templates to customize look and feel.
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
You can now open them in your browser by typing:
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.
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.
You’ll notice your docs look a bit different than mine.
You can change this by setting the
html_theme setting in your
Go ahead and set it like this:
html_theme = 'sphinx_rtd_theme'
If you rebuild your documentation, you will see the new theme:
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.
Have some extra time left? Check out these other cool things you can do with Sphinx.
Sphinx is quite configurable,
which can be a bit overwhelming.
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:
This is all well documented in the Sphinx The build configuration file doc.