Ceci est une ancienne révision du document !
The Mysteries of the Sphinx
Greetings fellow Beings. Beaming from somewhere in time and space, I come again to, hopefully, provide some well needed information.
This month, I will present something that I’ve wanted to do for the last 8 months. As always, something would always get in the way and require my attention. This month, I purposefully refused to let anything take precedent over this topic.
As you can see from this month’s title, it has to do with Sphinx. Not the massive limestone structure in Giza, but the Python software package used to create documentation.
Sphinx uses reStructured Text (rst) files to create HTML and, if desired, EPUB files, that can be easily included in your project.
So let’s jump right in and see how to get started.
Installing Sphinx
First, the people at Sphinx suggest you use a virtual environment to install into. So, here are the steps. First, create the virtual environment and activate it. I usually create a directory in my project folder called “sphinx” and start from there. Open a terminal and use these steps.
$ python -m venv .venv
$ source .venv/bin/activate
Next, use pip to install it into the virtual Python instance.
(.venv)$ pip install sphinx Collecting sphinx…
This takes only about a minute on my machine. Now check the version.
(.venv) $ sphinx-build –version sphinx-build 7.2.6
Ok. Now, run the quickstart script which will ask questions about your project, then create the folders and the base files for you.
(.venv)$ sphinx-quickstart docs Welcome to the Sphinx 7.2.6 quickstart utility.
Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).
Selected root path: docs
You have two options for placing the build directory for Sphinx output. Either, you use a directory “_build” within the root path, or you separate “source” and “build” directories within the root path.
Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
Project name: sandbox
Author name(s): Greg Walters
Project release []: 0.1
If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language.
For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
Project language [en]:
Here is what the directory tree looks like.
. └── docs
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
Now, change to the /docs/source/ folder. There are two files there that we will eventually need to edit. First is the index.rst file and the second is the conf.py file. If you plan to use any graphics files like screenshots of your applications, create an “images” folder in the source folder as well. So let’s change to the /docs/source folder.
(.venv)$ cd docs/source
Now, let's look and see what the index.rst file contains.
(.venv)$ cat index.rst
.. sandbox documentation master file, created by
sphinx-quickstart on Sat Dec 16 10:04:46 2023. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.
Welcome to sandbox's documentation!
.. toctree::
:maxdepth: 2 :caption: Contents:
It’s basic but that’s all we need to get started.
Notice at the top of the file is a line that starts with two dots. That is a commented line, so it will be ignored by Sphinx when creating the HTML file.
Then at the bottom of the file are three lines that will be used to create the table of contents.
The two dots that start each of these lines is called a directive. Anytime you want to do something special, outside of bold or italic markings, which are the same commands as markdown (.md), so to set a word or phrase as bold you would wrap the phrase with two asterisks and italics would be just one.
We’ll look at more directives in a little bit.
Now, to create an HTML version of the documentation for our project, use the sphinx-build script, at least the first time. This should be done in the folder that you originally set up, which, in my case, was /sphinx. This tells Sphinx where the source folder is and the build folder. The build folder will hold our finished HTML files. So change back to the sphinx (parent of everything) folder.
(.venv)$ sphinx-build -M html docs/source/ docs/build/
Running Sphinx v7.2.6 making output directory… done building [mo]: targets for 0 po files that are out of date writing output… building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources… [100%] index looking for now-outdated files… none found pickling environment… done checking consistency… done preparing documents… done copying assets… copying static files… done copying extra files… done done writing output… [100%] index generating indices… genindex done writing additional pages… search done dumping search index in English (code: en)… done dumping object inventory… done build succeeded.
The HTML pages are in docs/build/html.
That’s it. Now let’s look at getting it to actually create something. We’ll have to modify the index.rst file for that.
Editing the Sphinx Document
After trying many markdown editors, my favorite one to use is formiko. Formiko is included in most Linux distributions, but you can also find it at https://github.com/ondratu/formiko .
This editor ticks all the boxes for me to be my ‘go to’ .rst editor. Automatic spell checking, syntax highlighting, it’s all there. It also handles .md files.
The config.py file
For the most part, the only thing that I’ve ever had to modify here is the next to last line, which sets the theme file for the output (we’ll discuss themes below). This line is by default…
html_theme = 'alabaster'
If you want a different built-in theme file, just change the word ‘alabaster’ to the theme of your choice. For many of the other themes, it is also this simple.
Images in your Sphinx Document
In order to use images in your Sphinx document, you will need to create a sub-folder to hold them in the source folder. Do NOT use spaces in your image filenames.
Adding an image is pretty simple. You use the directive “.. image::” a space and then the filename with the path. So it would be something like this…
.. image:: /images/startup.png
There are options that include height, width, scale, and others. Here is an example of the image directive with the scale option.
.. image:: /images/sclbDemo20.png
:scale: 50%
Notice the spacing. Spacing is VERY important in rst, so if there is an error in the build, that would be the first place to look. For the most part, any directive options are indented 4 spaces. Also note that when continuing your text after an image directive (or just about any directive), it is important to have at least one blank line between the directive and your next text.
Theming your Document
You will need to edit the config.py file in order to change the theme for your document. There are MANY themes available to suit your style. There is a web page that provides a gallery of the themes at
https://sphinx-themes.org/#theme-mozilla-sphinx-theme .
My favorite theme is the bizstyle, which is built in. There are 10 different themes that are already built into Sphinx. Any other themes that you might want to use, will have to be downloaded and installed. Some themes have special steps you need to do, so follow the instructions for that theme.
As I said above, you will have to edit the config.py file to set the theme that is used.
Some other useful directives
There are WAY too many directives to try to cover them all here, and there are plenty of web sites that cover rst directives, so I’ll cover only a few of the ones that I commonly use.
Remember that how the directives look in the finished product depends on the theme you are using.
Admonitions
I use admonitions often to highlight notes or warning statements. According to one of the rst directive web pages “Admonitions” (“safety messages” or “hazard statements”) can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded.”
Here is a simple note in code…
.. Note::
The actual entry method depends on your Operating system. Some of the options might not be available on your system.
Remember the spacing is VERY important both before and after the directive.
Shown top right is what it looks like rendered using the bizstyle theme (but can look different in other themes). Code blocks
You can use code blocks to highlight console commands or code snippets. Here is the directive for highlighting a terminal command.
.. code:: console
python colours1.py
And below is a screenshot of how it gets rendered.
Language based code blocks
Like terminal code blocks, you can use language specific code blocks as well.
Create an instance of the widget giving it all of the information you might want use to customize the look of the widget (top right).
And how it gets rendered is shown below.
Bulleted lists
Bulleted lists are REALLY easy in rst. Just place a dash in front of each item.
From top to bottom on the left side of the image are:
- Hex value
- RGB Value
- Calculated Closest Colour name
- Calculated Best Colour for text on this colour.
Renders out like this… As I said, there are many other directives you can use (and probably will) so in the next section I’ve provided a few of my favorite reStructured Text “go to” web pages.
Helpful links
https://www.sphinx-doc.org/en/master/tutorial/first-steps.html
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
https://docutils.sourceforge.io/docs/user/rst/quickref.html
https://docutils.sourceforge.io/docs/ref/rst/directives.html#top
Looking at my page count, it’s about time for me to close for this month.
Until next time, as always; stay safe, healthy, positive and creative!