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.

See also

If you are not familiar with TOML, see the TOML documentation.

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

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.

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.