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.
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:
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
make.bat: The manual build code if you aren’t using an IDE
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>
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.
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.