requirements-declare-documenteer-technote (TN002)#
Group |
Default severity |
|---|---|
Structural |
Warning |
A Sphinx technote’s requirements.txt must declare documenteer[technote].
The [technote] extra is what installs the technote theme and Sphinx configuration, so a requirements file that omits it (or omits documenteer entirely) builds with whatever happens to be installed — which breaks in the isolated environments that CI and tox create.
A missing requirements.txt is treated as an empty one, so this rule fires for it too.
This rule is skipped for non-Sphinx technotes.
Example of a failing technote#
sphinx==8.1.0
[TN002] requirements.txt should declare 'documenteer[technote]' so the technote theme and Sphinx configuration are installed.
A bare documenteer requirement without the extra also fails, since the extra’s dependencies (the technote theme among them) would not be installed.
How to fix it#
Declare documenteer with the [technote] extra in requirements.txt:
documenteer[technote]>=2.0,<3.0
The version bounds are recommended so that a future Documenteer major release cannot break your build unexpectedly. If your file pins Sphinx as a separate line, remove that line as well — that is TN003.
See also#
TN003 — do not pin Sphinx separately from
documenteer[technote].Migrate legacy reStructuredText/Sphinx technical notes — the migration tool writes a modern
requirements.txt.