03. 12. 2020 Charles Callaway Documentation

Creating Documentation in Sphinx

Most small open source documentation projects use Markdown to create their project documentation. After all, it has a minimalistic and thus easy-to-learn syntax, does all the basics well, renders very quickly (even quickly enough to create a real-time WYSIWYG viewer), and is almost universally supported across popular web platforms like GitHub.

At some point, though, your project gets big enough that the simplicity of Markdown starts hampering you — you begin to need additional features it just doesn’t have. For instance, the Alyvix documentation needs features like multi-page indexing, search, CSS support, definable types, and on and on and on.

That’s when you start searching for alternatives, and many people come across Sphinx, a multiplatform (because it’s built on Python) documentation environment with a number of downloadable extensions and multiple ways to let you customize just about everything.

Setting up the Sphinx Environment

Sphinx uses Python, so you’ll need to install both. Luckily, Sphinx combines their installation instructions. If you’re going to be creating a large site, or updating frequently, you should also consider installing an IDE like PyCharm with Git integration.

Installation via pip will give you most of the tools you need to begin. The best way to start is to run Sphinx’s Quickstart script:

> sphinx-quickstart

It’ll ask you a few questions, then create the basic files and directories you need in the current directory, including:

conf.py: The main configuration file
index.rst: The starting content page corresponding to index.html
Makefile, make.bat: The manual build code if you aren’t using an IDE
_static/: The directory that will contain font files, javascript, CSS, etc.

At this point you can start editing index.rst, and creating other .rst files, images, and subdirectories in this same directory.

To build an HTML version of your documentation, either run make html or directly call Sphinx via Python. For instance, I use the following command:

C:\Python37\python.exe -m sphinx.main -E -a -b html <source-dir> <target-dir>

Now you’re ready to start learning how to add more configuration options in conf.py, the basics of reStructuredText, and perhaps install some
extensions.

To view your output (HTML) files, load index.html into your browser from your _build/ directory, or copy the entire contents of the _build/ directory to your website.

If you’re building a large site, or you want multi-device support, consider installing a theme like RTD which contains many more features than the default theme.

Planning and Writing Your Documentation

You should probably start by distributing your content into a set of multiple pages. If you have a lot to write, create subdirectories each containing related files. Then use the table of contents in your index.rst file to point to them. For instance, our Alyvix index looks like this:

.. toctree::
   :maxdepth: 2
   :name: toc_master
   :hidden:

   getting_started.rst
   test_case_building.rst
   test_case_execution.rst
   test_case_data_format.rst
   video_tutorials.rst
   glossary.rst
   release_notes.rst
   Alyvix Server User Manual <https://alyvix.com/learn/server/>
   get_in_touch.rst

(The Alyvix documentation is itself completely open source, you can take a look at our Github repository.)

Some of the filenames point to a single self-contained file, others point to RST files containing their own indices that in turn point to files in their subdirectories.

Since RST syntax is a lot more complicated than Markdown, it makes sense to be able to see a visual catalog of its features. For instance, in Alyvix we created a stylesheet that’s not reachable from the index (since it’s not included in any index) but is visible if you know the address.

There you can scroll down looking for the effect you want to create. And if you notice at the very top right of the page, you’ll see a “View page source” link that let’s you see the RST source the page was created from. It’s included by default in every Sphinx-built page, which is a defining feature of its open source nature.