In this post I’m testing Sphinx!

>Installing

$ pip install sphinx

$ sphinx-quickstart
[...]
> Separate source and build directories (y/n) [n]: y
[...]
> Project name: sphinx-blog
> Author name(s): Erasmus Cedernaes
> Project release []:
[...]
> Project language [en]:
[...]

Initially the directory structure looks as follows

$ tree
.
├── build/
├── make.bat
├── Makefile
├── requirements.txt
└── source/
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

4 directories, 5 files

There is a combined tool for rebuilding and serving the web page called sphinx-autobuild which can be installed using pip (pip install sphinx autobuild) and used as:

$ sphinx-autobuild -b html

I however had some trouble with using it together with Vim since it rebuilt too many files and twice for each file I changed (due to Vim creating .swp-files?). I therefore switched to using the good old faithful entr (get it with apt install entr on Debianesque systems):

# Do this in one terminal
$ while sleep 1; do find . | entr -d make html; done
# And this in another terminal session
$ python -m http.server 4001 --directory "build/html"

I even added these as targets in the Makefile:

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build
PORT          ?= 4001

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

livehtml:
	sphinx-autobuild -p $(PORT) -b html -i ".*.*" "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)

watchhtml:
	while sleep 1; do find "$(SOURCEDIR)" | entr -d $(MAKE) html; done

webserver:
	python -m http.server $(PORT) --directory "$(BUILDDIR)/html"

.PHONY: help livehtml watchhtml webserver Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

They can then be built using make watchhtml and make webserver. Go to the page by visiting localhost:4001.

>Page format

Sphinx pages are written in reStructuredText (RST) which is a much more potent language than Markdown, but also more difficult. It is quite similar to LaTeX in that it has a lot of predefined commands for common things like linking to manpages and rfc documents, labeling sections so they can be inter- and intralinked, adding footnotes/references and adding code sections.

Here is a simple introduction to RST with a lot of good examples (similar to RST primer from the Sphinx documentation, but simpler to understand). If you want to get a lot more technical about the tools then check out this page. Otherwise check out the specifications for RST which contains all of the details.

>Changing the design

Let’s say we would like to change something in the design of our website (which everyone will do). Then, first we have to check what theme we are using in the conf.py file:

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

Alabaster is the default theme according to the Sphinx theming page. There is some info on that page on where we should look for further documentation for the Alabaster theme. According to it we will need to go to the alabaster theme page.

If we want to add something to the sidebar, then we need to set html_sidebars in conf.py. The default value can be found here:

html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'localtoc.html',
        'relations.html',
        'searchbox.html',
        'donate.html',
    ]
}

>Adding a blog

I think one of the best alternatives is to use an extension called ABlog (pip install -U ablog).

>Thoughts

It is very hard to find the correct documentation for all of the settings. I have basically just searched online for the keywords that I think might be relevant in the conf.py file.

There are several extensions available.

The boilerplate that is available makes it quick to set up a project with a nice looking structure. Sphinx seems to be most suitable for documenting code and libraries.