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.

[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 ISO8601 string. 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

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.