Adapting Sphinx for Cahute

Adding an additional footer mention

However, one modification I could not do using Furo's customisation options was adding an arbitrary additional mention to the footer. I wanted to add one to credit Massena as the author of the cover image present at the top of every page.

In order to do this, I had to override Furo's page.html template to add my mention, which meant copying it, replacing it the extends directive with {% extends "!page.html" %} in order only to override the footer block (closest to the mentions), and updating the contents of the block to include the mention. Note that I also had to set templates_path in conf.py, in order for Sphinx to take my template override into account.

See page.html for the result.

Integrating Mermaid

Cahute's documentation includes diagrams, such as sequence diagrams for communication protocol flows (see CAS40 flows for an example). These diagrams use Mermaid through the sphinxcontrib-mermaid Sphinx extension, which adds the .. mermaid:: reStructuredText directive I can use.

However, Mermaid doesn't play nice with Furo's dark/light theme switch by default, as no Mermaid theme plays well with both, so I needed to add a Javascript snippet to detect dark/light theme (including dynamically, once the page / diagrams have loaded), and update the theme used by Mermaid.

The full code can be found in conf.py, set as the mermaid_init_js attribute that is used by sphinxcontrib-mermaid to replace the default template. A preview of the result is the following:

function isDarkMode() {
    const color = (
        getComputedStyle(document.body)
        .getPropertyValue("--color-code-foreground")
    );

    if (color == "#d0d0d0")
        return true;

    return false;
}

const observer = new MutationObserver(function(mutations) {
    mutations.forEach(function(mutation) {
        if (
            mutation.type != "attributes"
            || mutation.attributeName != "data-theme"
        )
            return;

        // ...
    });
});

(function (window) {
    // ...
    observer.observe(document.body, {attributes: true});
})(window);

import mermaid from "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs";

function initializeMermaid(isStart) {
    mermaid.initialize({
        startOnLoad: isStart,
        theme: isDarkMode() ? "dark" : "base",
        darkMode: isDarkMode(),
        securityLevel: "antiscript"
    });
}

function recomputeMermaid() {
    const nodes = document.querySelectorAll(".mermaid");
    nodes.forEach(node => {
        /* Restore the original code before reprocessing. */
        node.innerHTML = node.getAttribute("data-original-code");

        /* Remove the attribute saying data is processed; it is not! */
        if (node.hasAttribute("data-processed"))
            node.removeAttribute("data-processed");
    });

    initializeMermaid(false);
    mermaid.run({nodes: nodes, querySelector: ".mermaid"});
}

Rendering TOC tree sections side-by-side on the index

By default, Sphinx renders table-of-contents (TOC) trees as a simple list, which takes up a lot of space to display less content:

We want to render such TOC trees on the index as two columns, if we have enough space (width).

First, we need a way to target the index page only using CSS. Fortunately, docutils places all of its rendered context within a <section> tag with an id set to a normalized version of what's in the document title. Here, since our section title is Cahute |version| (where |version| is a substitution replaced by the actual version on rendering), the generated identifier for the <section> tag is cahute-version, so we can target #cahute-version.

Next, in order to make two columns, we can use flexboxes. This will result in the following code, placed in custom2.css:

#cahute-version .toctree-wrapper > ul {
    display: flex;
    list-style-type: none;
    flex-wrap: wrap;
    padding-left: 0;
    gap: .5em 1em;
}

#cahute-version .toctree-wrapper > ul > li {
    display: inline-block;
    flex: 1 0 20em;
}

Which renders as the following:

Overriding the HTML translator

Some of the modifications below will require me to implement HTML rendering for some custom elements, or update HTML rendering for some elements. In order to do this, I write my class inheriting from sphinx.writers.html.HTMLTranslator, and set the translator using sphinx.application.Sphinx.set_translator.

The HTML translator is written as a classic docutils node visitor, using visit_<node class name> and depart_<node class name> methods. Visit methods can also raise the following exceptions:

• SkipNode: the children won't be visited, the departure method won't be called;

• SkipChildren: the children won't be visited, the departure method will be called;

• SkipDeparture: the children will be visited, the departure method won't be called.

Adding a cover image to the page title

I commissioned Massena to make an illustration for Cahute, to both include in promotional material for Cahute (forum posts and social media only for now) as well as include as a cover image for page titles in the documentation, to give it a little more panache.

In order to add the illustration as a cover image for the page titles, I need to override the HTML rendering code for docutils' title node, i.e. override visit_title.

The HTML output for a page title, identified by checking we are not in a special context and that our section level is 1 (i.e. if we are not within a container node, even indirectly), is replaced from <h1>...</h1> to something like the following:

<div class="title-container">
    <div class="title-contrast"><hr /></div>
    <h1>...</h1>
</div>

Fixing section titles in the sidebar

Cahute's documentation uses Diátaxis, and I consider this to be a contract between the reader and the writer; therefore, the structure must appear as clear as day, in every place it can.

Until recently, all top-most sections appeared in the sidebar unseparated, their nature (guide, topic or reference) only appearing in their title. However, it is possible in Sphinx to add titles to sections, by adding a :title: property on the corresponding .. toctree:: directive on the index page.

However, when doing this, the title also appeared above the TOC tree, which was repetitive with the title above and undersirable:

In order to remove this, in our custom HTML translator, we need to add another block to visit_title to identify such cases and raise a SkipNode in this case. The correct identification algorithm I've found is the following:

• If our parent is an sphinx.addnodes.compact_paragraph instance with its toctree attribute set. This corresponds to two cases: the TOC tree in the sidebar, and the TOC tree within the index page; however, we only want to identify the second one.

• If our grandparent is a docutils.nodes.compound with the toctree-wrapper class, which allows us to only select the second case.

This results in the following block:

if (
    isinstance(node.parent, addnodes.compact_paragraph)
    and node.parent.get("toctree")
    and isinstance(node.parent.parent, nodes.compound)
    and "toctree-wrapper" in node.parent.parent.get("classes", ())
):
    raise nodes.SkipNode()

Adding a feature list presentation

In order to highlight the Cahute features, I wanted to make an element to present them as this:

Out of a list resembling the following:

.. feature-list::

    * - |feat-transfer|
      - File transfer between storages
      - With ``p7``, transfer files from and to storages on
        fx-9860G compatible calculators, over USB and serial links!
    * - |feat-program|
      - Program backup
      - With ``CaS``, extract programs from all CASIO calculators since
        1991, over USB and serial links!

.. |feat-transfer| image:: feat-transfer.svg
.. |feat-program| image:: feat-program.svg

In order to do this, I did the following:

• Create the feature_list, feature, feature_icons, feature_title and feature_detail nodes. The idea was to obtain this in the document obtained from parsing the original document:

  <feature_list>
    <feature>
      <feature_icons>
        <image uri="..."></image>
      </feature_icons>
      <feature_title>
        ...
      </feature_title>
      <feature_detail>
        ...
      </feature_detail>
    </feature>
    <feature>
      ....
    </feature>
  </feature_list>
  

• Create the FeatureListDirective which obtains this tree from a two-level list passed as the content, and register it using sphinx.application.Sphinx.add_directive;

• Add the HTML rendering functions in the custom HTML translator, e.g. visit_feature_list, and so on.

Adding a system list presentation

In order to highlight the systems supported by Cahute, as well as present the guides associated with them directly, I wanted to make an element to present them as this:

Out of a list resembling the following:

.. system-list::

    * - |system-arch|
      - :ref:`feature-topic-system-arch`
      - :ref:`Install from the AUR <install-guide-linux-aur>`
      - :ref:`Install using GiteaPC <install-guide-linux-giteapc>`
      - :ref:`Build natively <build-guide-linux-sh>`
    * - |system-apple|
      - :ref:`feature-topic-system-macos`
      - :ref:`Install using Homebrew <install-guide-macos-homebrew>`
      - :ref:`Build natively <build-guide-macos-sh>`

.. |system-arch| image:: guides/install/arch.svg
.. |system-apple| image:: guides/install/apple.svg

In order to do this, I did the following:

• Create the system_list, system, system_icon and system_detail nodes. The idea was to obtain this in the document obtained from parsing the original document:

  <system_list>
    <system>
      <system_icon>
        <image uri="..."></image>
      </system_icon>
      <system_detail>
        ...
        <bullet_list>
          <list_item>
            <reference>...</reference>
            <reference>...</reference>
            ...
          </list_item>
        </bullet_list>
      </system_detail>
    </system>
    <system>
      ....
    </system>
  </system_list>
  

• Create the SystemListDirective which obtains this tree from a two-level list passed as the content, and register it using sphinx.application.Sphinx.add_directive;

• Add the HTML rendering functions in the custom HTML translator, e.g. visit_system_list, and so on.

Protocol 7.00 command directive

In the Known Protocol 7.00 commands by CASIO and Known Protocol 7.00 command extensions in fxRemote pages, you can find a reference of Protocol 7.00 commands, all having the same format with different argument usage. Every command has the following presentation:

• A title with the command code in ASCII-HEX, and name in quotes;

• A reference of the D1 to D6 parameters, with description and format;

• A description of the command;

• An example of the command, including a checksum (!).

In the related guide, everything but the title is automated using the seven-command directive. For example:

.. seven-command::
    :code: 02
    :d1: Baud rate in decimal format.
    :d1-example: 19200
    :d2: Parity, among "ODD", "EVEN" or "NONE".
    :d2-example: EVEN
    :d3: Stop bits, "1" or "2".
    :d3-example: 2

    If connected to the passive device using a serial link, this command
    signifies a request to communicate using different serial parameters.

    .. note::

        The serial speeds are limited to the following speeds (or baud
        rates): 300, 600, 1200, 2400, 4800, 9600 (*by default*), 19200,
        38400, 57600 and 115200 bauds.

    See :ref:`protocol-topic-seven-update-serial-params` for more
    information.

This example will generate a presentation such as the following:

In order to do this, I've created the SevenCommandDirective and registered it using sphinx.application.Sphinx.add_directive.