{"id":10248,"library":"sphinx-needs","title":"Sphinx Needs","description":"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.","status":"active","version":"8.0.0","language":"en","source_language":"en","source_url":"https://github.com/useblocks/sphinx-needs","tags":["sphinx","documentation","requirements","needs","specifications","extension","rst"],"install":[{"cmd":"pip install sphinx-needs","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import sphinx_needs","symbol":"Extension","correct":"extensions = ['sphinx_needs']"}],"quickstart":{"code":"# conf.py\nextensions = ['sphinx_needs']\n\n# my_document.rst\n.. need:: My first requirement\n   :id: my_req_1\n   :status: open\n   :tags: example, important\n\n   This is the detailed description of my first requirement.\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.1.0"},{"fix":"Replace `extra_options_sum` with equivalent functionality using `dynamic_functions` in your `conf.py`.","message":"The `extra_options_sum` configuration option was removed in version 7.0.0. Any usage of this option will lead to build errors.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.1.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Add `'sphinx_needs'` to the `extensions` list in your `conf.py`: `extensions = ['sphinx_needs']`.","cause":"The `sphinx_needs` extension has not been correctly added to your Sphinx project's `conf.py` file.","error":"sphinx.errors.No directive 'need' failed: unknown directive type 'need'"},{"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'}]`.","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`.","error":"NeedException: Provided need_status 'CUSTOM' is not defined in needs_statuses"},{"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.","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`.","error":"NeedException: Schema validation error for field 'my_field': String does not match pattern '^XYZ_.*$'"}]}