Notes on Using Sphinx¶
Here are some quick notes on running Sphinx successfully. Each topic will be elaborated upon at the right point during our class.
Starting a Sphinx project¶
The wonder of a properly designed framework
is that it begins by positioning you at a working starting point
instead of leaving you to wander endlessly through a README
that, after dozens of steps, leaves you guessing which step
you did improperly to have wound up with a broken install.
Sphinx gets you started with sphinx-quickstart
.
Here is how a quick-start session will look,
paying attention only to its prompts and how you should respond
(which is mostly by pressing Return over and over),
when you use it to create a new project:
$ sphinx-quickstart
Welcome to the Sphinx quickstart utility...
> Root path for the documentation [.]: doc
> Separate source and build directories (y/N) [n]:
> Name prefix for templates and static dir [_]:
> Project name: trianglelib
> Author name(s): Brandon
> Project version: 1.0
> Project release [1.0]:
> Source file suffix [.rst]: .rst
> Name of your master document (without suffix) [index]: index
> Do you want to use the epub builder (y/N) [n]: n
> autodoc: automatically insert docstrings ... (y/N) [n]: y
> doctest: automatically test code snippets ... (y/N) [n]: y
> intersphinx: ... (y/N) [n]:
> todo: ... (y/N) [n]:
> coverage: ... (y/N) [n]:
> pngmath: ... (y/N) [n]:
> mathjax: ... (y/N) [n]: y
> ifconfig: ... (y/N) [n]:
> viewcode: include links to the source code ... (y/N) [n]: y
> Create Makefile? (Y/n) [y]: y
> Create Windows command file? (Y/n) [y]: y
Sphinx layout¶
After you have succeeded in quick-starting,
your project should look something like this,
if we imagine that you created your doc
Sphinx directory
right next to your trianglelib
Python package directory:
your-project/
|-- doc/
| |-- Makefile
| |-- _build/
| |-- _static/
| |-- _templates/
| |-- conf.py
| |-- index.rst
| `-- make.bat
|-- setup.py
`-- trianglelib/
|-- __init__.py
|-- shape.py
`-- utils.py
The index.rst
is your initial documentation file,
whose table of contents you will expand
as you add additional .rst
files to this directory.
Hints¶
Here are a few adjustments you can make to a Sphinx project once you have its files laid out and set up.
Sphinx is sensitive to indentation — blocks and code snippets end when the indentation level returns to its previous level — but Sphinx is usually forgiving about how far exactly you indent; you can generally choose freely how far to indent, so long as you are then consistent about sticking to that level. Sphinx is much like Python in this regard, but without a strong community preference for a particular number of spaces per indentation level.
Build your documentation by changing directory to the directory that contains the
Makefile
and then running:make html
You can view the documentation by running Python’s built-in web server, opening
http://localhost:8000/
in your web browser, and navigating into the_build/html
directory:python -m SimpleHTTPServer
Feel free to create directories beneath
doc
for groups of.rst
files that do not belong at the top level. Simply refer to such files in yourindex.rst
table of contents using adir/filename
syntax so that Sphinx can find them.You can get rid of the line that says “Contents:” in
index.rst
since it causes a bizarre blank page in the PDF output.To make prettier PDFs, remove the whole section in
index.rst
named “Indices and tables.”Do not despair if you realize later that you need an extension that you failed to answer
y
to during the quick-start; simply go into theconf.py
and add the extension to theextensions
list and make any other changes the extension needs. You can always simply re-run the quick start to make a new project with the extension active, then rundiff
between your ownMakefile
and the new one to see what the differences are.You can use Semantic Newlines to be friendly to your version control.
Here is a small diagram of how I think of documentation, which we will use as a rough guide during class:
developer developer new user writing new code reading code | | | v v v tutorial <--> topical guides <--> API reference
Helping autodoc find your package¶
In order to run autodoc
directives on your package,
the Python interpreter that is running Sphinx for you
needs to be able to import your package.
You can test whether Python can see your package
by testing whether this command returns without error:
python -c 'import your_package'
There are three general approaches
to making your package available to autodoc
.
Have your package’s top-level directory sit right next to your Sphinx
Makefile
andconf.py
and all of your top-level RST text files. When you typemake
inside this directory and it goes off and runs Sphinx, your package will be visible because it is sitting in the current working directory.The downside: you usually want your package sitting out by itself in your source distribution, not mixed in or sitting beneath its own documentation.
Set the Python path environment variable to point to the directory containing your package. You can do this with an
export
statement that you run before you start building your documentation:export PYTHONPATH=/home/brandon/trianglelib
Or you can set the Python path only for the build command itself, leaving your shell variable settings pristine:
PYTHONPATH=/home/brandon/triangle-project make html
The downside: You either have to remember to manually set this environment variable each time you run Sphinx, or you have to create and maintain a small shell script as a separate file that will remember to set the path and run Sphinx.
If you have installed Sphinx inside a virtual environment — which is a really, really great idea — then you can install your under-development package there too by using the pip
--editable
flag:pip install -e /home/brandon/triangle-project
Once you have run this command, the Python running inside of this virtual environment is permanently able to
import
trianglelib
without further ado. (Assuming that you do not remove the project from your filesystem!)The downside: When you check the project out on to a fresh machine, you either have to always remember to manually set up the virtual environment the right way, or you have to keep a shell script in the repository that sets it up for you each time. (Even though that is a good idea anyway.)
Assuming that your package and its documentation are part of the same source repository — as they should be — they will always have the same relative position on the filesystem. In this case, you can simply edit the Sphinx
conf.py
so that itssys.path
configuration entry points at the relative position of your package:sys.path.append(os.path.abspath('../triangle-project'))
All upside: this is, in my opinion, the best approach, as it always goes along for the ride with your repository, and works immediately upon repository check-out without having to rely on any intermediate setup steps.
Deployment¶
We will discuss this topic in depth, but here are some links for your further reference when the class is complete:
It should be possible to export the contents of
_build/html
to any file-system-based web service and serve it as static content.You can package the documentation in a ZIP file and upload it using the “edit” page for your Python package, and it will appear at the URL:
http://pythonhosted.org/<project-name>
Detailed instructions for this procedure live at:
The powerful and popular Read the Docs service lets you configure your GitHub repository so that every time you push a new version of your software, the documentation gets automatically rebuilt and made available at:
https://readthedocs.org/projects/<project-name>/
Read the Docs also supports custom host names if you want your documentation to appear beneath your own project sub-domain. More information is available at:
Creating a PDF is nearly as simple as running:
make html
Except that you have to have the Latex typesetting system installed, which is a daunting task on many platforms and operating systems. On my own Ubuntu Linux laptops, I need to install several packages before even attempting it:
texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
See the Sphinx documentation for several other supported formats!
We will tackle simple theming tasks during the tutorial’s second half; remember that the PyEphem project is a good living example of how to completely replace the Sphinx HTML themes with one of your own, so that you are essentially using Sphinx to build your own web site.