Sphinx-Needs

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.

Docs-as-Code based documentation with Sphinx-Needs

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 objects created by Sphinx-Needs in Docs-as-Code documentation

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

Configured Life Cycle objects for SW development documentations

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'


Docs-as-code based analysis with Sphinx-Needs

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.


Learn more

Boost your developer's doc-as-code experience

    Easily manage needs objects within the explorer view and ensure data validation during document creation.   


Try it yourself!

Trace every artifact in your software project

ubTrace offers insights and analytics for development projects, seamlessly integrating with Git branch and tag names.


Try it yourself!

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

Share by: