sphinx-needs

What it is and what it does

Sphinx-Needs extends Sphinx documentation with a system for defining and managing structured objects—requirements, specifications, implementations, and test cases—directly within your documentation source. You define these objects using simple directives, link them together, and then query and visualize them across your entire documentation build. The extension provides filtering, table generation, flow diagrams, and pie charts to analyze your needs, making it useful for projects that need to track requirements alongside their documentation.

The package is built on top of Sphinx and integrates with its standard build pipeline. It depends on requests, jsonschema-rs, and several other utilities. You activate it by adding it to your Sphinx conf.py extensions list, then use custom directives in your reStructuredText files to declare and link needs. The visualization and filtering features help teams maintain traceability between requirements and implementation across documentation.

Use it for:

• Track system requirements and specifications in technical documentation alongside implementation details.
• Generate traceability matrices and requirement-to-test-case mappings for compliance and verification workflows.
• Visualize dependencies and relationships between requirements using flow diagrams and tables.
• Manage custom need types tailored to your project's workflow beyond the default requirement types.
• Filter and query needs by status, priority, or custom attributes to generate reports from documentation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Sphinx-Needs is a Sphinx extension that lets you define, link, and filter requirement-like objects (requirements, specifications, implementations, test cases) within documentation, with customizable types and visualization directives.

Yes. Sphinx-Needs is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and solves a real problem for teams that need to embed requirement traceability in their documentation. Install friction is low and Python 3.10 or later support is current. Use it if your project needs to track and link requirements, specifications, or similar structured objects within Sphinx documentation.

Install

sphinx-needs on PyPI

pip install sphinx-needs

uv add sphinx-needs

poetry add sphinx-needs

Installing sphinx-needs

Before you install

Low install friction; pure Python wheel. Active maintenance with a release 3 days ago. Requires Python 3.10 or later and 9 runtime dependencies including sphinx and requests.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute freely with minimal restrictions.

Quickstart

pip install sphinx-needs

# In conf.py:
extensions = ["sphinx_needs"]

# In your .rst file:
.. req:: REQ
   :title: System shall process data
   :status: open

Requires Python 3.10 or later. Sphinx must be installed and configured in your documentation project.

Verify before relying

• Whether the plotting extra (matplotlib) is required for most use cases or optional for advanced visualization only.
• Performance characteristics when managing large numbers of needs in a single project.
• Whether custom need types can reference external data sources or are limited to inline definitions.

Package facts

Evidence: sphinx_needs-8.3.1-py3-none-any.whl

Tags

More Utilities packages