Sphinx Needs Comparison

This page maps concepts from Sphinx Needs to their equivalents in Antora Tracer. Both are language-agnostic documentation-tool extensions — they document projects written in any programming language. The key differences are in their markup languages and hosting platforms: Sphinx Needs uses reStructuredText (or Markdown via MyST) with the Sphinx builder (Python-based), while Antora Tracer uses AsciiDoc with the Antora site generator (Node.js-based).

Directive Mapping

Sphinx Needs Antora Tracer Notes

Sphinx Needs	Antora Tracer	Notes
`:need:` directive	`[item, role=requirement]`	Sphinx has separate directives per type; Antora Tracer uses one macro with a `role` attribute
`:spec:` (specification)	`[item, role=design]`	Design/specification items
`:test:` (test case)	`[item, role=test]`	Test items
`:impl:` (implementation)	`[item, role=implementation]`	Implementation items
`:req:` directive	`or`	Sphinx links via directive role; Antora Tracer links via inline relationship macros
`needs.json`	YAML configuration file	Antora Tracer uses YAML config for roles, relations, matrices
`needs_id_prefix`	Manual ID assignment	IDs are user-defined, no enforced prefix
`needs_types`	`roles` in `traceability.yml`	Both define the valid types for items

:need: directive

[item, role=requirement]

Sphinx has separate directives per type; Antora Tracer uses one macro with a role attribute

:spec: (specification)

[item, role=design]

Design/specification items

:test: (test case)

[item, role=test]

Test items

:impl: (implementation)

[item, role=implementation]

Implementation items

:req: directive

or

Sphinx links via directive role; Antora Tracer links via inline relationship macros

needs.json

YAML configuration file

Antora Tracer uses YAML config for roles, relations, matrices

needs_id_prefix

Manual ID assignment

IDs are user-defined, no enforced prefix

needs_types

roles in traceability.yml

Both define the valid types for items

Feature Comparison

Feature Sphinx Needs Antora Tracer Notes

Feature	Sphinx Needs	Antora Tracer	Notes
Documentation tool	Sphinx (Python)	Antora (AsciiDoc)	Different ecosystems
Item definition	Multiple directives (`:need:`, `:spec:`, etc.)	Single `[item]` macro with `role` attribute	Antora Tracer is simpler — one macro for all types
Role system	Configurable via `needs_types`	User-defined roles via YAML	Both are configurable; Sphinx uses separate directives per type, Antora Tracer uses one macro with a `role` attribute
Relation system	Configurable via `needs_links` (v7.0+)	User-defined relation types per role pair	Both support custom link types; Antora Tracer validates allowed relations between roles
Matrices	`needtable` directive	Config-driven matrix generation	Both produce traceability matrices
Coverage	`needpie` charts	Coverage reports with status badges	Antora Tracer generates HTML coverage reports
Export	needs.json, needs builder API	Neo4j CSV and Cypher export	Different export targets
Presets	Not available	4 built-in presets (requirements-eng, agile, medical, minimal)	Antora Tracer ships with ready-to-use configurations
Custom fields	`needs_fields` with JSON Schema, predicates, defaults, dynamic functions (v7.0+)	Not available	Sphinx-Needs lets you define typed, validated fields on each need
TOML configuration	Supported via `needs_from_toml`	Not available	Sphinx-Needs supports TOML as alternative to conf.py
Variant data	`needs_variant_data` for build-time filter switching	Not available	Sphinx-Needs supports conditional content via variant data
Validation	Schema validation via `needs_fields`, constraint checking, dead link detection	Role-based relation validation + duplicate detection	Both validate; Sphinx-Needs validates custom field schemas, Antora Tracer validates role-to-role relations
CLI	Via Sphinx build	Standalone CLI with 6 commands	Antora Tracer works outside the documentation build
Link rendering	Inline via directives	`traceability:outgoing[]` and `traceability:incoming[]` macros with configurable style (list, table, inline)	Antora Tracer separates data (inline macros) from rendering (links macro)
Matrix navigation	Links in needtable	Clickable deep links from matrix cells to item definitions	Antora Tracer matrices are interactive — click any ID to jump to source

Documentation tool

Sphinx (Python)

Antora (AsciiDoc)

Different ecosystems

Item definition

Multiple directives (:need:, :spec:, etc.)

Single [item] macro with role attribute

Antora Tracer is simpler — one macro for all types

Role system

Configurable via needs_types

User-defined roles via YAML

Both are configurable; Sphinx uses separate directives per type, Antora Tracer uses one macro with a role attribute

Relation system

Configurable via needs_links (v7.0+)

User-defined relation types per role pair

Both support custom link types; Antora Tracer validates allowed relations between roles

Matrices

needtable directive

Config-driven matrix generation

Both produce traceability matrices

Coverage

needpie charts

Coverage reports with status badges

Antora Tracer generates HTML coverage reports

Export

needs.json, needs builder API

Neo4j CSV and Cypher export

Different export targets

Presets

Not available

4 built-in presets (requirements-eng, agile, medical, minimal)

Antora Tracer ships with ready-to-use configurations

Custom fields

needs_fields with JSON Schema, predicates, defaults, dynamic functions (v7.0+)

Not available

Sphinx-Needs lets you define typed, validated fields on each need

TOML configuration

Supported via needs_from_toml

Not available

Sphinx-Needs supports TOML as alternative to conf.py

Variant data

needs_variant_data for build-time filter switching

Not available

Sphinx-Needs supports conditional content via variant data

Validation

Schema validation via needs_fields, constraint checking, dead link detection

Role-based relation validation + duplicate detection

Both validate; Sphinx-Needs validates custom field schemas, Antora Tracer validates role-to-role relations

CLI

Via Sphinx build

Standalone CLI with 6 commands

Antora Tracer works outside the documentation build

Link rendering

Inline via directives

traceability:outgoing[] and traceability:incoming[] macros with configurable style (list, table, inline)

Antora Tracer separates data (inline macros) from rendering (links macro)

Matrix navigation

Links in needtable

Clickable deep links from matrix cells to item definitions

Antora Tracer matrices are interactive — click any ID to jump to source

Migration Path

If you’re moving from Sphinx Needs to Antora Tracer:

Replace :need:\ with [item, role=requirement], :spec:\ with [item, role=design], etc.
Move your needs types into traceability.yml roles field
Define allowed relations in traceability.yml relations section
Replace :links: with inline relationship macros (``)
Replace needtable directives with matrix definitions in traceability.yml
Use npx antora-req-trace process instead of the Sphinx build for traceability

Key Differences

For a comparison of Antora and Sphinx as publishing platforms (HTML, PDF, versioning, navigation), see .

Sphinx Needs is tightly integrated with Sphinx. Antora Tracer is tightly integrated with Antora. Both are language-agnostic — they document projects written in any programming language.

Sphinx Needs defines need types via needs_types configuration — each type gets its own directive name (.. req::, .. spec::, etc.). Antora Tracer uses a single [item] macro with a role attribute — one syntax for all types. Both let you define your own domain model.

Sphinx-Needs provides needflow for in-page graph visualization with PlantUML or Graphviz. Antora Tracer provides traceability:graph[] and `` macros for in-page graphviz/DOT visualization, plus Neo4j export for external graph queries.

Sphinx Needs is mature and well-established. Antora Tracer is newer but follows the same traceability principles with a more flexible, config-driven approach. Choose based on your documentation toolchain: Sphinx (reStructuredText/Markdown) or Antora (AsciiDoc).