Docs-as-Code based Life Cycle Management
Sphinx-Needs enables your team to create, manage and analyze requirements, specifications, test cases, and more inside Sphinx-based documentation
Sphinx-Needs is the de facto standard to manage requirements, specifications and similar life cycle management objects inside docs-as-code based documentations, which are created and managed by the Sphinx documentation generator. It is designed to support developers during documentation creation and allows to automate and configure most tasks to fulfill company internal processes and guidelines.
It can be used for free, no matter if working on private, academic or commercial projects. The used MIT license allows to adopt the source code to company specific needs or to reuse components for internal projects.
To fit best into an already existing tool environment, Sphinx-Needs provides Connectors to synchronize data between your documentation and for instance JIRA or codebeamer.
As Sphinx-Needs is maintained mainly by the german tool-development company useblocks, professional support is available and company specific solutions can be created quite fast with the help of useblocks.
Creation of life cycle / needs objects
Sphinx-Needs allows life cycle management in Sphinx based docs-as-code documentations by providing the ability to create so called "need objects". Need objects, no matter if used for requirements, specifications or something else, are created directly inside rst-files of a Sphinx project. This means they can be defined at any location and between any text of the document, so that the organization of needs can based on your preferences. For instance you could collect all requirements inside a single file, but let the related specifications be defined inside the developer manual, between class diagrams and code guidelines.
Like other Sphinx features, need objects are created by using the related directive, e.g. ".. req:: My requirement". No special syntax needs to be learned. Sphinx-Needs is 100% compliant to Sphinx and reStructuredText.
.. req:: ECU voltage support
:id: REQ_001
:status: open
The ECU must support a voltage range from
**11.0** V to **12.5** V
.. spec:: Power supply unit
:status: open
:links: REQ_001
Use our internal product ``5345BCV_12V`` for
power supply.
.. image:: /_images/5345BCV_12V.png
:align: center
:width: 75%
Life cycle / Need objects
Need objects get defined by reStructuredText (rst) in your preferred IDE. They can be used for everything: requirements, specifications, test cases and runs, employees, products, ...
Links
Needs can be linked to each other and a need can have multiple outgoing links. Incoming links get calculated automatically. And even links to needs from external projects can be set.
Full docs-as-code support
The content of each need supports all features from Sphinx and reStructuredText (rst). It supports images, tables, code blocks and all Sphinx extensions, e.g. Jupyter notebooks.
External data syncronisation
Needs can be created by hand or automatically by importing json data or based on external data from e.g. JIRA or github.
Contact useblocks for details.
Powerful Configuration for customizable Life Cycle Management solutions
Sphinx-Needs is designed to be highly configurable to support each type of use case. It is used and tested in Automotive SW development projects with over 1.000 engineers and more than 100.000 highly customized life cycle objects. Over 40 configuration options support Process and Quality engineers to create company specific docs-as-code concepts for any kind of SW development teams.
conf.py
# Define own need types
needs_types = [
{ "directive: "req",
"title": "Requirement",
"prefix: "R_",
"color": "#BFD8D2",
"style": "node" },
{ "directive": "spec"
"title": "Specification",
"prefix": "S_",
"color": "#FEDCD2",
"style": "node"},
{ "directive": "test",
"title": "Test Case",
"prefix": "T_",
"color": "#DCB239",
"style": "node"}]
# Define own options
needs_extra_options = [ "integrity", "assignee" ]
# Define own link types
needs_extra_links = [
{ "option": "checks",
"incoming": "is checked by",
"outgoing": "checks" },
{ "option": "implements",
"incoming": "is implemented by",
"outgoing": "implements" }]
document.rst
.. req:: My first requirement
:id: REQ_001
:integrity: ASIL-D
A requirement
.. spec:: My first specification
:id: SPEC_001
:assignee: Mr. Nice Guy
:implements: REQ_001
A specification
.. test:: Test case for spec
:id: TEST_001
:checks: SPEC_001
A test case
Custom options
Each need can have custom options to store data. These options can be used for filtering, automations to define the layout and style of a need.
Own layouts and styles
The exact position and structure of data inside a need can be completely customized. Also the graphical style like colors can be defined and set automatically based on need data.
Life cycle process checks
Define checks for allowed option values or link conections.
Check for allowed status names, ID expressions and more.
> 40 configuration parameters
Sphinx-Needs can be configured by over 40 parameters to support company specific use cases.
Docs-as-Code based Analysis
Sphinx-Needs allows SW teams to create analysis reports for their used life cycle elements (like requirements) in their docs-as-code based documentation.
Static and dynamic tables, flowcharts, pie charts, list and simple inline numbers can be used and are based on powerful filter possibilities.
From
simple
word-based search, over
complex
filter strings to
almighty
Python code with access to all internal data elements.
Sphinx-Needs allows you to get each kind of answer out of the data.
All open requirements
---------------------
.. needtable::
:type: req
:status: open
Traceability of my needs
------------------------
.. needflow:: Traceability
:filter: "component_x" in tags and status != "rejected"
Amount of needs per type
------------------------
.. needpie:: Type spread
:labels: Requirements, Specifications, Test Cases
type == 'req'
type == 'spec'
type== 'test'
Multi data representation
Show and analyze Sphinx-Needs data in tables, flow charts, lists, pie charts, gantt charts or even in sequence charts
Strong filter options
Filters for tables and co. can be defined via simple options, a python-based filter string or even by own python functions.
Dynamic Tables
Sort and filter tables on-the-fly inside your browser.
Graphical Traceability
"needflow" is based on PlantUML and can be used to create helpful flowcharts to show the connection network between needs.
Licenses and Subscriptions
Sphinx-Needs
Sphinx-Needs is available under the MIT license, which is an official Open-Source license. For commercial support and maintenance, a Support subscription is available, which brings most benefits to your project teams and supports the development of Sphinx-Needs.
| MIT | Supporter Subscription | |
|---|---|---|
| Free Usage | Private, Academic, Commercial | Private, Academic, Commercial |
| Code Access | ✔ | ✔ |
| Own Changes | ✔ | ✔ |
| Bug Reports | ✔ | ✔ |
| Feature Requests | ✔ | ✔ |
| Priorised Issues | ✗ | ✔ |
| Telephone / E-Mail Support | ✗ | ✔ |
| Purchase | free | Buy |
Our solutions for enterprise users
Sphinx-Needs Online Training (4 hours session)
The maintainers of Sphinx-Needs give your team a four-hour lesson on any Sphinx and Sphinx-Needs-related topic.
Boost your developer's doc-as-code experience
Easily manage needs objects within the explorer view and ensure data validation during document creation.
Trace every artifact in your software project
ubTrace offers insights and analytics for development projects, seamlessly integrating with Git branch and tag names.
Contact
Do you have any questions or any hints or just an idea for a feature? Great, we love to get in contact with you. So please do not hesitate and drop us some lines.
Get in contact with us.
useblocks GmbH
Schopenhauerstr. 71
80807 Munich
Germany
