Sphinx Basics

Sphinx is a web-based documentation platform based on Python - allowing you to write documentation in simple MarkDown formats. I have been testing Sphinx for some time.

When MarkDown or rST - restructuredText - is used, you can use a text-editor like Notepad, Notepad++ or VS-Code, and archive in e.g., Git for full version control. This makes it natural to use for developers - especially if you place the documentation near the source-code. Links to internal as well as external documents and figures are easily supported. It is very easy to include source-code in monospace-fonts with colored background - inline and in blocks. There are also extensions for e.g., PlantUML.

The documentation is built into html-pages (and javascript) with a TOC - Table of Contents - and freetext search is automatically included. This output can be run on any webserver - and it may also be run directly from the file-system on your PC (Windows or Linux).

There is a selection of themes that typically organize the web-page in a main reading part and a TOC part. This is all configured in a single Python-file, and you can customize in several ways - e.g., by adding standard CSS - Cascading Style Sheets. A good example is Sphinx Tutorial which is using "read-the-docs" theme.

Summarizing the advantages - and showing bullets:

• Web-based with links, images, etc.
• Write in simple MarkDown - or the more powerful restructuredText with support for tables
• Developer friendly workflow - using VS-code with syntax/preview, git and Python
• Runs on webserver - but also from files

Another view - showing table-layout (coloring from this site):

Here is a screenshot of VS-Code with MarkDown and Preview - showing how easy it is to write and see the result immediately using a plugin.

Beware of Python Versions

Python is a fantastic and versatile tool. If you have used it, you probably know that when you build something in Python, you need to maintain control of the version of Python you are using - which libraries are used etc. If you have several things on your PC that each are built with Python, you can easily get into a maintenance nightmare where libraries are incompatible with each other. Thus, it is strongly recommended to have a specific version for Sphinx - independent on whatever Python you are using.

You can use a container (e.g., Docker or Podman). It is also easy to use Pythons's built-in .venv - virtual environment. However, be aware that the .venv does not exist until you have done the basic clone from git of a repo and the basic Sphinx install around it.

Thus - if you do not use a container for it all, I recommend a dedicated folder on your PC with a Python installation for Sphinx. I had three bat-files: One for copying a minimal Python from a server to a central folder on my PC, one for initialising a given folder, and one for building.

Transitioning to Sphinx

It is very easy to write documentation in your editor and do a fast build to see the resulting HTML.
You can find plugins for VS-Code that will give you an instant view of the output. This can be nice when getting to know MarkDown, but you will probably not use it so much in the long run.

You may have existing documentation in e.g., Word, Powerpoint or Excel that you want to see inside Sphinx. It is possible to convert such documents with Pandoc to MD or rST - exporting figures to selected folders.

If you still want to keep your original documents as "single source of truth" you may instead link to them - or "wrap" them into Sphinx.

Folder structure

The following shows a folder structure where I have retrieved a git repo with documentation and installed Sphinx on the PC - using a Python virtual environment. Note that you can start with git init and sphinx-quickstart to get up & running (not including the .venv).

Note that .gitignore is used to avoid checking in python virtual environment and generated files

   my_repo                          <-- Root of git repository. Using .gitignore to avoid checking in generated files.
                ├───.venv                        <-- Python virtual environment for building the docs. NOT IN GIT.
                │   ├───Include
                │   ├───Lib
                │   │   └───site-packages        <-- Tons of python packages are installed here.
                .....
                .....
                └───docs                         <-- Root for documentation source files. Goes into git repo - except _build folder.
                    ├───Subsystem1                <-- MarkDown or rST for Subsystem1
                    ├───Subsystem2                <-- MarkDown or rST for Other subsystem
                    ├───Subsystem3              
                    ├───Data                      <-- Data files used in the documentation - e.g., CSV files for tables 
                    ├───HowTo                     <-- Task-oriented guides that help you achieve specific goals.
                    ├───Images                    <-- Images used in the documentation. Basically follows the same structure as the docs.
                    │   ├───Subsystem1            <-- Images related to Subsystem1 
                    │   ├───Subsystem2
                    │   ├───Subsystem3
                    │   ├───HowTo
                    │   ├───Tools
                    ├───Tools                     <-- Descriptions of the various tools used when developing 
                    ├───_build                    <-- Generated files here - index.html is the main entry point. NOT IN GIT. 
                    │   ├───.doctrees             <-- .doctrees is intermediary output for faster rebuild. Not shipped.
                    │   │   ├───Subsystem1
                    │   │   ├───Subsystem2
                    │   │   ├───Subsystem3
                    │   │   ├───HowTo
                    │   │   └───Tools
                    │   ├───Subsystem1            <-- The HTML for the pages
                    │   ├───Subsystem2
                    │   ├───Subsystem3
                    │   ├───HowTo
                    │   ├───Tools
                    │   ├───_images
                    │   ├───_sources              <-- The original source-files are included in the build for viewing
                    │   │   ├───Subsystem1
                    │   │   ├───Subsystem2
                    │   │   ├───Subsystem3
                    │   │   ├───HowTo
                    │   │   └───Tools
                    │   ├───_sphinx_design_static
                    │   └───_static
                    │       ├───css  
                    ....
                    ....
                    ├───_static                   <-- Static source files (does go into git) used in the documentation - CSS, JS, etc.
                    └───_templates

                

Document tree-view