HOC Sphinx Domain

Overview

The HOC Sphinx Domain is a Sphinx extension that allows to document HOC constructs in Sphinx. Given the extra effort to create a full-fledged domain, we’ve decided to hack it from the Python domain. Ideally we’d have a proper HOC domain, but that is an extra workload and we lack the required knowledge to build one. See https://github.com/neuronsimulator/nrn/issues/1540

Hacking the Python Domain

It is sometimes required to re-hack the domain to make it work with the latest version of Sphinx. To that end, the following script can be used to generate the domain from the Python domain:

cd docs
python3 generate_hocdomain.py

This script generates a HOC domain from the one available in the sphinx package and writes it to:

docs/domains/hocdomain.py

A comment is added at the top of the file to indicate that it is a generated file and the Sphinx version used to generate it.

Sphinx Setup

Like all Sphinx setup, the HOC Sphinx Domain is registered in docs/conf.py

# 1st step: make docs/domains available to Sphinx
sys.path.insert(0, os.path.abspath("./domains"))

# ....

# 2nd step: import hocdomain
import hocdomain  # Sphinx HOC domain (hacked from the Python domain via docs/generate_hocdomain.py)

# ....

# 3rd step: setup the HOC domain in Sphinx
def setup(app):
    # ...
    # Set-up HOC domain
    hocdomain.setup(app)