TOML-Doc Specification

The TOML-Doc specification defines a formal syntax for embedding documentation comments in TOML files. This specification ensures that parsers can unambiguously associate documentation with configuration items.

Doc-Comment Marker

The doc-comment marker is #: (hash followed by colon). This distinguishes doc-comments from regular # comments, which are ignored by the parser.

Formatting Rules

A parser must be able to unambiguously associate a doc-comment block with the TOML item (key or table) that it documents. This is enforced with two strict rules:

Separator Rule

A doc-comment block MUST be preceded by at least one empty newline.

This separates it from any preceding items or regular comments.

Attachment Rule

A doc-comment block MUST NOT be separated from the item it documents by any empty newlines.

This ensures the doc-comment is “attached” to the item immediately following it.

Valid Syntax Examples

Documenting a Table

[project]
name = "my-project"
version = "1.0.0"

# This is a regular comment. It will be ignored.

#: This doc-comment documents the 'dependencies' table.
#: It can be multi-line.
#:
#: .. spec:: All dependencies MUST be pinned.
#:    :id: S_DEPS_001
[project.dependencies]
flask = "==3.0.0"

Key points:

  1. There’s an empty line before the #: doc-comment (Separator Rule)

  2. There’s NO empty line between the doc-comment and [project.dependencies] (Attachment Rule)

  3. Regular # comments are ignored

Documenting a Key

[project.dependencies]
flask = "==3.0.0"

#: This docstring documents only the 'pytest' key.
#:
#: .. req:: Pytest must be version 7 or higher.
#:    :id: R_TEST_001
pytest = ">=7.0.0"

Hierarchical Documentation

You can document both parent tables and their sub-tables:

[project]
name = "my-project"
version = "1.0.0"

#: Documentation for the hatch build system.
#:
#: .. spec:: All hatch configuration must be tested.
#:    :id: S_HATCH_001
[hatch]

#: Documents the 'foo' subsection.
[hatch.foo]
my_foo_key = "value1"

#: Documents the 'bar' subsection.
[hatch.bar]
my_bar_key = "value2"

Invalid Syntax Examples

Missing Separator

[project]
name = "my-project"
# INVALID: No empty line before the doc-comment
#: This doc-comment is attached to nothing.
[project.dependencies]
flask = "3.0"

Error: Doc-comment violates the Separator Rule.

Detached from Item

[project.dependencies]
flask = "3.0"

#: INVALID: An empty line separates the
#: docstring from the item it should document.

pytest = ">=7.0.0"

Error: Doc-comment violates the Attachment Rule.

Embedding Sphinx Directives

Doc-comments can contain any reStructuredText content, including Sphinx directives. This is particularly powerful when combined with sphinx-needs:

#: Configuration for the test suite.
#:
#: .. req:: All tests must pass before merging.
#:    :id: R_TEST_001
#:    :status: open
#:    :tags: testing, ci
#:
#: .. spec:: Test coverage must exceed 80%.
#:    :id: S_TEST_001
#:    :status: implemented
#:    :links: R_TEST_001
[tool.pytest.ini_options]
testpaths = ["tests"]

The directives are processed by Sphinx during the documentation build, creating trackable requirements and specifications.

Implementation Notes

Parsers implementing this specification:

  1. MUST use a TOML parser that preserves comments (e.g., tomlkit)

  2. MUST validate both the Separator Rule and Attachment Rule

  3. SHOULD provide clear error messages with line numbers when rules are violated

  4. MAY provide auto-formatting tools to fix common violations