Overview of technote configuration¶
Technote builds technote documents using Sphinx. Virtually anything you can accomplish in a general Sphinx project your can also include in a technote. To simplify the set up process, Technote provides its own configuration system that layers on top of Sphinx’s. This page explains that configuration system.
The technote.toml and conf.py files¶
Besides the content file, technotes have at least two other files: technote.toml and conf.py.
technote.toml is unique to Technote, and is what you’ll work with most often.
This file is where you can both mark up bibliographic metadata about your technote and also configure the Sphinx build.
A basic technote.toml file might look like this:
[technote]
id = "SQR-000"
series_id = "SQR"
# title = "The *technical note* system"
canonical_url = "https://sqr-000.lsst.io"
github_url = "https://github.com/lsst-sqre/sqr-000"
github_default_branch = "master"
date_created = 2015-11-18T00:00:00Z
date_updated = 2015-11-23
organization.name = "Vera C. Rubin Observatory"
organization.ror = "https://ror.org/048g3cy84"
[[technote.authors]]
name.given = "Jonathan"
name.family = "Sick"
orcid = "https://orcid.org/0000-0003-3001-676X"
affiliations = [
{ name = "Rubin Observatory", ror = "https://ror.org/048g3cy84" }
]
[technote.status]
state = "deprecated"
note = "This is a comment about the status of this document."
[[technote.status.supersceding_urls]]
url = "https://sqr-000.lsst.io/"
title = "The technical note system"
[[technote.status.supersceding_urls]]
url = "https://sqr-006.lsst.io/"
[technote.sphinx.intersphinx.projects]
python = "https://docs.python.org/3/"
To learn about all the available keys in technote.toml, see technote.toml reference.
This user guide also includes a number of how-to guides on specific aspects of the configuration.
The other configuration file is conf.py — the standard Sphinx configuration file.
At a minimum, the Sphinx configuration imports the base technote configuration:
from technote.sphinxconf import *
If you are using a theme for an organization, you will import its configuration module instead. For example, Rubin technote use a configuration from Documenteer:
from documenteer.conf.technote import *
Primer on TOML¶
technote.toml is written in TOML syntax.
If you’ve written YAML before, you’ll be fairly comfortable, but TOML does have a number of distinct features.
The first unique feature to note is that mappings or objects (key-value pairs) are described with tables and those tables are preceded by their key in square brackets.
[technote] # the technote table
id = "SQR-000" # a key in the table, aka technote.id
Tables can be nested.
For example, the sphinx table inside the technote table:
[technote.sphinx]
extensions = ["sphinx_diagrams"]
TOML supports resolving keys in tables using dots (.) to separate each level of hierarchy.
So the same TOML configuration as above can be expressed as:
[technote]
sphinx.extensions = ["sphinx_diagrams"]
The technote.toml configuration frequently uses arrays of tables, such as when listing authors.
Arrays of tables are the key name, in double brackets.
You can repeat the tables for each item:
[[technote.authors]]
name.given = "Jonathan"
name.family = "Sick"
[[technote.authors]]
name.given = "Frossie"
name.family = "Economou"
To learn all about the TOML syntax, see the `TOML specification website`__.
How the configuration system works with the Sphinx build¶
If your are curious how the Sphinx build uses technote.toml,
When a Sphinx build starts (by running sphinx-build), it automatically reads the project’s configuration file (conf.py).
In technote projects, the conf.py file always imports the base technote configuration module, either directly or through a theme’s configuration file (from technote.sphinxconf import *).
The Technote configuration module, in turn, loads technote.toml and then sets Sphinx configuration variables based on that input.