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

sphinx-quickstart

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

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

html:
    @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

clean:
    sphinx-clean

.PHONY: html clean

If managed by git, add .gitigore

build/*

Configuration

Changes to source/conf.py

extensions = [
  'sphinx_charts.charts',
  'sphinx_last_updated_by_git',
  'sphinxcontrib.jquery',
]

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

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 @@
   size|74597949
   blocks|145712
  -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: https://docs.citusdata.com/en/v11.0/get_started/concepts.html
.. _Cluster Management: https://docs.citusdata.com/en/stable/admin_guide/cluster_management.html

.. 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

  postgresql_views
  citus_trial

Charts

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