Sphinx Development Environment¶
We use a Python library called Sphinx to generate documentation from ReST files.
If you haven’t already installed Python 3, see Installing Python. When you come to the end of the Python installation section, come back to this guide.
Installing Sphinx on Linux¶
In Ubuntu, Sphinx is very easy to install. You can install it for either Python 2 or Python 3. Since we use the latter, we’ll install that.
To install on Ubuntu, simply run...
$ sudo apt install python3-sphinx pandoc
Installing Sphinx on Mac¶
We can install Sphinx on Mac using either Homebrew or MacPorts.
Installing Via MacPorts¶
$ sudo port install py36-sphinx pandoc $ sudo port select --set sphinx py36-sphinx
Choosing an Editor¶
ReST files are just plain text files written in the ReStructuredText markup language. Thus, you can edit them in any text editor.
Writing and Editing Documentation¶
To get started editing documentation, open Atom and go to OK. This will tell Atom that you’re working in that folder.. Go to the repository you want to work in, and just click
The file tree on the left will show you the entire repository. If you don’t see
the file tree, click
Ctrl + \ to toggle it. Sphinx should have a
dedicated folder, which is docs for most projects. The ReST (*.rst) files can
be found in
By the way, Atom has some pretty fancy integration with Git. Newly added files appear in the file tree as green, and modified files as orange. (Those colors go away once you commit your changes.) On the bottom-right corner of Atom, you can see the branch that you’re currently on.
Single-click a file in the file tree to preview it (the name in the tab will be in italics), and double-click a file to open it. Then, just start editing!
To preview how a *.rst would look once rendered by Sphinx, press
Ctrl + Shift + E. The preview isn’t fancy, but it is sufficient to
give you a basic idea while working.
Panes are resizable. I usually make the preview window just narrow enough that I can see the right-hand margin line on the editing window.
source/index.rst is the main file in your documentation. Open the file
in Atom. To add a file to the automatic table of contents tree, list it below
.. toctree:: :maxdepth: 2
You only need to list the name of the file, without the extension. If it is
within a subfolder in
source/, just write out the relative path.
For example, if you had the file
source/bar/, you can add them like this:
.. toctree:: :maxdepth: 2 foo bar/baz
Note that I lined everything up, so both of my new entries have
the same number of leading spaces as
:maxdepth: 2. ReST is VERY
finicky! You should line things up exactly.
Adding a New File¶
To add a new file to your documentation, in Atom, go to
Ctrl + S and save the file in
docs/source folder (or a subfolder thereof) with the
A good filename should be all lowercase, with underscores where necessary. For
goldilocks.rst would be a good file name for the Goldilocks
Documentation pages can be quite long, and that’s fine. Sphinx subdivides large documents beautifully, so you can generally devote one single document to one single module, section, or topic.
Once you click Save, Atom will know to treat the file as a ReST document.
Rendering Final Output¶
It is super simple to render the gorgeous output of your documentation with
Sphinx. In your Terminal, go to your
docs/ folder, and simply type...
...to list out all the supported formats. My favorite is HTML, which generates a snazzy, searchable web version. To output to HTML, type...
$ make html
Double-check the Terminal output. If it complains about any errors or warnings, be sure to fix them! Errors are pretty obvious in Sphinx - missing documents, malformed tables, and so on.
Because Sphinx is the standard way of creating documentation for Python projects, the #python IRC channel is a really good place to get help.
Once the HTML is created, go to
build/html/, and open
in your favorite web browser.
Setting Up Documentation¶
If your project already has documentation, skip this section!
In the repository for the project that you want to create the documentation for, run...
$ mkdir docs $ cd docs
This creates a new folder
docs for our documentation, and navigates into
it. Then, run...
- Below are the settings you should select during Quickstart. I’ve marked ENTER for those options that you should use the default on.
- Root path: ENTER
- Separate source and build:
- Name prefix for templates and static dir:
- Project name: <name of your project>
- Author name(s): MousePaw Media
- Project version: <short project version>
- Project release: <long project version>
- Project language:
- Source file suffix:
- Name of your master document:
- Do you want to use the epub builder?:
- Use defaults for the rest of the options.
You can change most of those options again later.
Before continuing, you should also edit your
.gitignore file, adding
This ensures that Sphinx’s output is not tracked by the repository.
source/conf.py is the configuration file for Sphinx. This is where you
change things like project name, author, copyright, and version, as well as
build options and theme.
If you just created this documentation directory, open this file in Atom,
and then look for
html_theme. Change this from
sphinx_rtd_theme. The new line should look like this:
html_theme = 'sphinx_rtd_theme'