Sphinx Needs

8.0.0 · active · verified Fri Apr 17

Sphinx Needs is a Sphinx extension for managing requirements, specifications, and other 'needs' within documentation. It allows users to define, link, filter, and visualize needs directly in reStructuredText documents. The current version is 8.0.0, and it follows a regular release cadence with major updates typically every few months and patch releases as needed.

Common errors

```
sphinx.errors.No directive 'need' failed: unknown directive type 'need'
```
cause The `sphinx_needs` extension has not been correctly added to your Sphinx project's `conf.py` file.

fix Add `'sphinx_needs'` to the `extensions` list in your `conf.py`: `extensions = ['sphinx_needs']`.
```
NeedException: Provided need_status 'CUSTOM' is not defined in needs_statuses
```
cause Since version 7.0.0, Sphinx-Needs strictly validates custom statuses (and tags/extra options) against defined schemas. The status 'CUSTOM' is used in your `.rst` but not declared in `needs_statuses` in `conf.py`.

fix Define your custom status in `conf.py` under `needs_statuses`. For example: `needs_statuses = [{'name': 'open', 'description': 'Open status'}, {'name': 'CUSTOM', 'description': 'My custom status'}]`.
```
NeedException: Schema validation error for field 'my_field': String does not match pattern '^XYZ_.*$'
```
cause A custom field value in your `.rst` document does not conform to the regex pattern or other constraints defined in its schema under `needs_extra_options` in `conf.py`.

fix Either adjust the value of the custom field in your `.rst` file to match the schema's requirements, or update the schema definition in `conf.py` if the constraint is too strict for your use case.

Warnings

breaking Starting with version 7.0.0, Sphinx-Needs enforces stricter schema validation for `needs_extra_options`, `needs_statuses`, and `needs_tags` by default. Existing configurations with undeclared or invalid custom fields, statuses, or tags may cause build failures.
Fix: Ensure all custom `needs_extra_options`, `needs_statuses`, and `needs_tags` are correctly defined and comply with their respective schemas in `conf.py`. If migrating, consider temporarily setting `needs_schema_validation_enabled = False` (version 6.1.1+) to debug.
breaking The format for `needs_global_options` changed significantly in version 5.1.0. Older configurations using the previous list-based format for global options will no longer work.
Fix: Update your `needs_global_options` definition in `conf.py` to the new dictionary-based format. Consult the official Sphinx-Needs documentation for the current structure.
breaking The `extra_options_sum` configuration option was removed in version 7.0.0. Any usage of this option will lead to build errors.
Fix: Replace `extra_options_sum` with equivalent functionality using `dynamic_functions` in your `conf.py`.
gotcha While schema validation is enabled by default since 6.1.1, disabling it via `needs_schema_validation_enabled = False` should be done with caution. It can mask data inconsistencies that may cause issues later or when re-enabling validation.
Fix: Prioritize fixing schema errors over disabling validation. Only disable temporarily for migration or debugging purposes, and re-enable as soon as possible to maintain data integrity.

Install

pip install sphinx-needs Install stable version

Imports

Extension
wrong:
```
import sphinx_needs
```
correct:
```
extensions = ['sphinx_needs']
```
Sphinx Needs is a Sphinx extension, not a regular Python library to be imported directly into application code. It's activated by adding its name to the `extensions` list in your Sphinx `conf.py`.

Quickstart

Add 'sphinx_needs' to the `extensions` list in your Sphinx project's `conf.py` file. Then, you can define needs using the `.. need::` directive in your reStructuredText (`.rst`) documents.

# conf.py
extensions = ['sphinx_needs']

# my_document.rst
.. need:: My first requirement
   :id: my_req_1
   :status: open
   :tags: example, important

   This is the detailed description of my first requirement.

view raw JSON →