Eric Radman : a Journal

Sphynx Development Notes

One of the most useful skills a Systems Engineer employees is a method of keeping personal notes. This serves as a form of documentation that is constantly revised that captures current knowledge of a system and the tricks to accomplishing specialized tasks effectively.

Note taking also services to keep long-term goals moving. On a daily basis write-ahead logging can provide short-term focus. By keeping a personal record of experiments is a reserve to draw on when the rest of the team will be most receptive to a change.

The organization for note-taking can a directory with plain text files, but a framework such as Sphynx provides a way to create personal notes that can be easily shared with a team.

Installing Sphynx

pkg_add py3-sphinx

And any custom extensions

pip install sphinx-material
pip install sphinx_last_updated_by_git
pip install sphinx-charts sphinxcontrib-jquery

To create the initial scaffolding, run


The default Makefile is not compatible with BSD make, but can be tweaked to solve this

SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = source
BUILDDIR      = build



.PHONY: html clean

If managed by git, add .gitigore



Changes to source/

extensions = [

html_theme = 'sphinx_material'

html_title = ''

html_show_copyright = False
html_show_sphinx = False
html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %z'


reStructuredText is a far more predictable than Markdown and is well worth the time to learn.

Syntax highlighting works well in most cases

.. code-block:: diff

  @@ -1,19 +1,19 @@
  -ctime|2021-09-09 20:43:52-04
  +ctime|2022-09-02 16:44:36-04

Use :: to indicate a block of text without a language.

Example document:

:Date: 2022-08-24
:Authors: Eric Radman

.. _Citus Concepts:
.. _Cluster Management:

.. highlight:: none

Citus Data Trial

In 2021 and 2022 Microsoft merged all of their enterprise features in the
open-source edition of Citus [...]

* `Citus Concepts`_
* `Cluster Management`_

The index document is fully automatic

Radman Development Notes

.. toctree::
  :maxdepth: 2



Sphinx Charts strikes a near perfect balance between ease of use and flexiblity using the Plotly JSON schema

.. chart:: charts/atime_size.json

  Storage use by last access time

Example JSON chart source:

  "data": [
      "sort": false,
      "hole": 0.1,
      "name": "Size in MB",
      "type": "pie",
      "marker": {
        "colors": [ "#f99d27", "#f9c127", "#59ad9b", "#05b4d9", "#7dbecd", "#bbbbbb", "#dddddd" ],
        "line": {
          "color": "#fff",
          "width": 1
      "textinfo": "percent",
      "hoverinfo": "all",
      "labels": [ "< 1", "1 – 3", "3 – 6", "6 – 12", "12 – 24", "24 – 36", "> 36" ],
      "values": [ "52", "80", "120", "198", "450", "155", "12" ]
  "layout": {
    "width": 600,
    "height": 400,
    "autosize": true,
    "margin": { "t": 10, "b": 10, "l": 20, "r": 20 },
    "legend": { "title": {
        "text": "Age (months)"

The chart defenition is an async HTTP fetch, hence a local web server is required for preview

python3 -m http.server 8000

The Sphynx build doesn't know to rebuild a chart unless a page containing it changes. Use touch source/filename.rst to update the document mtime/ctime.

Removing Orphaned Files

If a file is removed from source/ Sphynx will not remove the corresponding HTML file from build/html/. A helper script can be used to find and remove these orphaned files

#!/bin/sh -e
# sphinx-clean

for f in $(cd build/html; ls *.html)
    case $f in
        search.html|genindex.html) continue ;;
    [ -f source/${f%.html}.rst ] || rm build/html/$f