technote.toml reference#

The technote.toml file contains metadata about the technote, along with configuration options for the Sphinx build. This page describes the schema for this file.

Configuration errors#

A technote.toml that does not validate stops the Sphinx build. The message names the file, then states each problem as an address in the file’s own vocabulary — such as [technote.lint] ignore or [[technote.authors]] author #1, field orcid — followed by a sentence saying what is wrong there. When the file has more than one problem, all of them are reported together and numbered, so they can be fixed in one pass rather than one build each. Sphinx prints its own Configuration error! banner around that message, along with the path of a saved traceback and an invitation to report the problem to Sphinx’s maintainers. That invitation can be ignored: the problem is in technote.toml, and the message inside the banner says where.

[technote]#

Required

The [technote] table is the root table for technote metadata and configuration in the technote.toml file.

id#

Optional

An internal identifier for the technote.

[technote]
id = "SQR-001"

series_id#

Optional

An internal identifier for a series or collection this technote belongs to.

[technote]
id = "SQR-001"
series_id = "SQR"

organization#

Optional

The organization that publishes the technote series. The value is a table with the same structure as [[technote.authors.affiliations]].

title#

Optional

The title of the technote. Use this metadata field to override the title in the content. Generally this metadata should not be set in technote.toml if the document title in content file is correct.

When this field is not set, the title is resolved from the document’s top-level heading once Sphinx has read the document. The resolved title is published in the HTML metadata and is available to every Sphinx builder, not just the HTML builder.

date_created#

Optional

Date and time when the technote was created. This should be set as an RFC 3339 (i.e., ISO8601) string. Either as a date (YYYY-MM-DD) or a date and time with a timezone (YYYY-MM-DDTHH:MM:SSZ).

TOML treats dates and date-times as native types, and therefore don’t use quotes:

[technote]
date_created = 2023-01-01T00:00:00Z

date_updated#

Optional

Date and time when the technote was last updated. This should be set as an RFC 3339 (i.e., ISO8601) string. Either as a date (YYYY-MM-DD) or a date and time with a timezone (YYYY-MM-DDTHH:MM:SSZ).

TOML treats dates and date-times as native types, and therefore don’t use quotes:

[technote]
date_updated = 2023-01-01T00:00:00Z

When date_updated is not set, Technote derives it from the publication event. For a technote published by CI, that event is the commit that was pushed, so the default is the committer date of the checked-out git commit (git log -1 --format=%cI). This is reproducible: rebuilding the same commit gives the same date. The same date is used everywhere the technote reports its updated date, including the sidebar, the Open Graph article:modified_time and Highwire citation_publication_date tags, and the schema.org dateModified property.

In detail, the default is the first available of:

The SOURCE_DATE_EPOCH environment variable (the reproducible builds convention, which Sphinx also honours), as an integer number of seconds since the Unix epoch.
The committer date of the checked-out git commit.
The current time, when the commit date cannot be read.

A derived date_updated is never earlier than date_created; if it would be, date_created is used instead. This matters because a bare date in technote.toml (YYYY-MM-DD) is interpreted as midnight UTC, so a commit made earlier the same local day in a timezone ahead of UTC would otherwise report the technote as modified before it was created.

A source directory that is not inside a git repository, or that is in a repository without any commits yet, falls back to the current time silently: those are ordinary states while a technote is being written. Any other failure to read the commit date — git is not installed, or git refuses the repository (for example the “dubious ownership” error it raises for a checkout owned by another user in a CI container) — also falls back to the current time, but emits a Sphinx warning first, so a build run with -W fails rather than quietly publishing a non-reproducible date. That warning can be silenced with suppress_warnings = ["technote.date_updated"] in conf.py.

Set date_updated explicitly to pin the date regardless of the commit being built.

version#

Optional

The version of the technote.

doi#

Optional

The most-relevant DOI that identifies this technote. This can be a pre-registerered DOI (i.e. for Zenodo) so that the DOI can be present in the released technote source.

[technote]
doi = "10.5281/zenodo.10385500"

The DOI can also be given as a https://doi.org URL or with a doi: prefix; it is normalized to the bare 10.NNNN/suffix form. A value that is not a syntactically-valid DOI is a configuration error. An empty string (doi = "") is treated the same as omitting the field.

When this field is set, the technote’s HTML acts as a DOI landing page: the DOI is published in the citation_doi, DC.identifier, and schema.org JSON-LD metadata, and is available to templates through the technote.doi and technote.doi_url Jinja context attributes.

canonical_url#

Optional

The URL where this technote is published.

github_url#

Optional

The URL of the GitHub repository hosting this technote.

github_default_branch#

Optional Default: main

The default branch of the GitHub repository.

[[technote.authors]]#

Authors are specified as an array of tables. In technote.toml, this means that each author is described with their own [[technote.authors]] table. You can have as many [[technote.authors]] tables as you need.

name#

Required

The author’s name, as it should appear in the technote:

[[technote.authors]]
name.given = "Vera"
name.family = "Rubin"

internal_id#

Optional

An internal identifier for the person. This can be used to associate an author with an organization’s author database.

email#

Optional

The author’s email address.

orcid#

Optional

The author’s ORCiD identifier. This should be specified as a full URL.

[[technote.authors.affiliations]]#

Optional

An author can have multiple affiliations. Each affiliation is a table in the [[technote.authors.affiliations]] array.

[technote.authors]
name.given = "Vera C."
name.family = "Rubin"
affiliations = [
  { name = "Department of Astronomy, University of Washington" },
  { name = "Department of Terrestrial Magnetism, Carnegie Institution of Washington" }
]

The above example used inline tables for each affiliation. If each affiliation has a large amount of metadata you can instead use the array of table TOML syntax:

[technote.authors]
name.given = "Vera C."
name.family = "Rubin"
[[technote.authors.affiliations]]
name = "Department of Astronomy, University of Washington"
[[technote.authors.affiliations]]
name = "Department of Terrestrial Magnetism, Carnegie Institution of Washington"

name#

Optional

The name of the entity.

internal_id#

Optional

An internal identifier for the entity. This field can be used to an organization’s database of affiliations.

address#

Optional

The address of the entity.

url#

Optional

The homepage of the entity.

ror#

Optional

The ROR identifier of the entity. This should be specified as a full URL. ROR is a research organization registry that provides a persistent identifier for research organizations, similar to ORCiD identifiers for individual researchers.

[[technote.contributors]]#

Optional

Besides authors, a technote can have other contributors such as reviewers, editors, and approvers. The [[technote.contributors]] array of tables is structured identically to the [[technote.authors]] array of tables, with the addition of role and note keys.

role#

Optional

The role of the contributor. This is an enumeration of one of the following values from the Zenodo schema:

ContactPerson
DataCollector
DataCurator
DataManager
Distributor
Editor
Funder
HostingInstitution
Producer
ProjectLeader
ProjectManager
ProjectMember
RegistrationAgency
RegistrationAuthority
RelatedPerson
Researcher
ResearchGroup
RightsHolder
Supervisor
Sponsor
WorkPackageLeader
Other

note#

Optional

A note describing the role of the contributor. This is particularly useful if the role is “Other”.

[technote.status]#

Optional

A technote is an evolving document. You can describe whether the technote is being actively drafted, stable, or deprecated with the [technote.status] table.

state#

Required

The state of the technote is an enumeration with the following allowed values:

draft: The technote is being actively drafted or is not in a complete state.
stable: The technote is stable and complete.
deprecated: The technote is deprecated and should not be used.
other: The technote is in some other state. Use the note key to describe the state.

note#

Optional

A note describing the state of the technote.

[[technote.status.superseding_urls]]#

Optional

A deprecated technote might be supersceded by other works. Use this array of tables to describe those links

url#

Required

The URL of the work that supersedes this technote.

title#

Optional

The title of the work that supersedes this technote.

[technote.license]#

Optional

The license of the technote.

[technote.license]
id = "CC-BY-4.0"

id#

Required

The SPDX identifier of the license.

[technote.sphinx]#

Optional

You can specify many configurations for the Sphinx build in the [technote.sphinx] table. Technote’s Sphinx configuration module, technote.sphinxconf, applies these values in the Sphinx conf.py file.

extensions#

Optional

An array of Sphinx extensions to enable, equivalent to the extensions list in Sphinx’s conf.py.

nitpicky#

Optional Default: false

Escalates build warnings to errors.

nitpick_ignore#

Optional

An array of two-item arrays specifying errors to ignore. The first item is the type (such as a role like py:class), and the second item is the target (such as a class name).

nitpick_ignore_regex#

Optional

Same as nitpick_ignore, but items are interpreted as regular expressions.

[technote.sphinx.intersphinx]#

Optional

Configurations for the intersphinx Sphinx extension.

[technote.sphinx.intersphinx.projects]#

Optional

A table of Sphinx project names and their root documentation URLs.

[technote.sphinx.intersphinx.projects]
python = "https://docs.python.org/3/"
sphinx = "https://www.sphinx-doc.org/en/master/"

[technote.sphinx.linkcheck]#

Optional

Configurations for the linkcheck Sphinx extension.

ignore#

Optional

An array of regular expressions for URLs to ignore when checking links.

[technote.lint]#

Optional

Configuration for tools that lint technotes, such as the documenteer technote lint command. Technote itself does not run lint rules, but it owns this table so that every tool reads the same configuration from technote.toml.

[technote.lint]
ignore = ["TN105"]

ignore#

Optional

An array of lint rule codes to skip for this technote. A rule code is an uppercase prefix that names the rule set, followed by a number (for example, TN105 for a generic technote rule or R101 for a Rubin-specific rule in Documenteer). Technote validates only the shape of each code; the linting tool documents which rules exist.