Sphinx – Absolute Beginners – Part 1
A series of tutorials on using the Sphinx Documentation system aimed at absolute beginners
Summary
Sphinx is a great tool that makes it easy to create good looking documentation in a range of output formats. If you’re a Python programmer it also makes it easy to use your existing docstring comments to form the basis of your documentation.
I’ve found using Sphinx for the first time a little difficult as much of the documentation seems to assume you know certain things. This series of posts provides a tutorial for the absolute beginner.
Ground Rules (for impatient programmers)
Now at this stage there’s a couple of things that are well worth knowing !
- Sphinx is good at auto-documenting Python code but that’s not its primary role. If you’re a Python programmer looking to auto-document your code it takes a while to understand that a lot of the facilities in Sphinx are nothing to do with what you’re after and that can be confusing.
- In Sphinx-land ‘the source files’ refer to the documentation configuration files. This confused me for a while whenever the term ‘source files’ was used I thought it meant my python source files.
Getting Spinx Installed
The prerequisites part of the Sphinx doco does a good job here but in summary:
- You want to have installed Python 2.4 or better
- Grab the source from the Sphinx Python Project Page or …
- … just use easy_install -U Sphinx
Next Steps
Sphinx has a great way to get you started and that’s the ‘quickstart’ script. In the next part of this tutorial series we’ll cover how to quickly and easily produce your first Sphinx project.