Validate a technote

Documenteer provides a command-line tool, documenteer technote validate, that checks a technote’s metadata and structure before it is built and published. Its most important job is verifying that every author has an internal_id that resolves in the Rubin author database (authordb.yaml), since these IDs are needed to mint a DOI for the technote. The command also checks that the content declares an abstract and that requirements.txt installs Documenteer correctly.

Rubin’s technote CI (from the rubin-sphinx-technote-workflows repository) runs this command so that builds fail early when a technote’s metadata is incomplete.

Run the validator

Run the validator from the root of a technote repository:

documenteer technote validate

If your technote uses the standard Makefile (see Migrate legacy reStructuredText/Sphinx technical notes), you can equivalently run:

make validate

The command prints each issue it finds, prefixed with its stable code (for example, [TN101]), followed by a summary. It exits with a non-zero status when any error-level issue remains, which is what causes a CI build to fail. Warning-level issues are reported but do not fail the command unless you pass --strict.

Options

--dir <path>, -d <path>

Path to the technote directory to validate. Defaults to the current directory (.). The command locates technote.toml, the content file (index.rst, index.md, or index.ipynb), and requirements.txt within this directory.

--strict, -s

Promote all warnings to errors. With this flag, any finding — including the warning-level checks below — causes the command to exit non-zero.

Checks

Each check has a stable, linter-style code so that findings are easy to triage (and, in the future, to except individually). Codes are grouped by concern: TN0xx for structural checks, TN1xx for metadata, and TN2xx for content.

Technote validation checks

Code	Group	Description	Default severity
TN001	Structural	technote.toml conforms to the technote schema. A schema failure short-circuits the remaining checks.	Error
TN002	Structural	requirements.txt declares documenteer with the [technote] extra.	Warning
TN003	Structural	requirements.txt does not pin Sphinx as a separate requirement (documenteer[technote] already constrains it).	Warning
TN101	Metadata	Every author declares an internal_id.	Error
TN102	Metadata	Each author’s internal_id resolves in the Rubin author database (authordb.yaml).	Error
TN103	Metadata	The author database is reachable so that IDs can be resolved.	Warning
TN201	Content	The content declares a non-empty abstract.	Error
TN202	Content	The abstract uses the .. abstract:: directive rather than an ordinary Abstract section heading.	Error

Note

Author internal_id values are the key to consistent author identification across Rubin documents, and a missing or unknown ID blocks DOI generation. See Maintaining author metadata to learn how to add and update the authors that TN101–TN103 check.

Related documentation

• Maintaining author metadata — add and update the authors that the TN1xx checks validate.

• Migrate legacy reStructuredText/Sphinx technical notes — the migration tool sets up the Makefile, requirements.txt, and abstract directive that these checks rely on.