Docs-as-Code based Life Cycle Management
Sphinx-Needs allows to create, manage and analyze requirements, specifications, test cases and more inside Sphinx-based documentations.
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 Enterprise 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.
See Sphinx-Needs Enterprise 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.
Sphinx-Needs Enterprise
Sphinx-Needs Enterprise provides a collection of solutions to embed
Sphinx-Needs into existing
tool chains. It allows to synchronize data between
Sphinx-Needs and services like
Jira,
Codebeamer,
Azure DevOps
or
Elasticsearch.
Import data
External data can be imported to documentation during build time, so that the documentation is in sync by 100% with the external services.
JSON support
To support baselines and less API usage of external services, data can be imported to a json file, which is compatible to the needs.json file format of Sphinx-Needs.
Directives & Scripts
Sphinx-Needs Enterprise provides solutions to be used inside a Sphinx project via directives. But also a common "sne" command is available to provide all functions also on CLI. This way Sphinx-Needs Enterprise is ready to be used inside Continuous Integration and Deployment pipelines.
Export data
Need objects created via Sphinx-Needs can also be exported to tools like Elasticsearch. This helps to support company specific Reporting and to create a search and analyzable history of your data.
Filter service data
The data to import can be filter by the related query language of the external service. For instance JQL for JIRA or cbQL for CodeBeamer.
Data mappings
Sphinx-Needs Enterprise supports the mapping of fields between the external service and the created need.
For instance the field "status" in Jira must be used as "state" in the created need.
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 |
Sphinx-Needs Enterprise
Sphinx-Needs Enterprise is licensed by default under the Business Source License (BSL), which is an "eventually Open-Source" license. This means the License can be used on private projects for free. Commercial and Academic projects must obtain a license.
The license fees are used by 100% for the maintenance and development of Sphinx-Needs Enterprise and Sphinx-Needs itself. This is our way to guarantee an ongoing and stable development of Sphinx-Needs and related Open-Source projects.
| BSL Private | BSL Academic + Commercial | |
|---|---|---|
| Subscription costs | Not needed | 800€ - 1200€ (Floating) |
| Supported project types | Private | Academic & Commercial |
| Code Access | ✔ | ✔ |
| Own Changes | ✗ | ✗ |
| Bug Reports | ✔ | ✔ |
| Feature Requests | ✔ | ✔ |
| Priorised Issues | ✗ | ✔ |
| Telephone / E-Mail Support | ✗ | ✔ |
| Purchase | Free | Buy |
Shop
-
![Sphinx-Needs Enterprise Floating Subscription (1 year)]()
Sphinx-Needs Enterprise Floating Subscription (1 year)
SKU 00008€1,200.00See details -
![Online Training (4 hours session)]()
Online Training (4 hours session)
SKU 00010€800.00See details -
![Enterprise Development Hour]()
Enterprise Development Hour
SKU 00009€120.00See details
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
by useblocks GmbH
