This package provides enterprise specific solutions for Sphinx-Needs.

Its main goal is to embed Sphinx-Needs in company specific tool environments by synchronizing data between Sphinx-Needs and tools like Jira, Doors, GitHub, CodeBeamer and more.

Sphinx-Needs Enterprise features are supporting the following services and tools:

Sphinx-Needs Enterprise provides directives and scripts to fetch data inside and outside of a Sphinx project.


This package is in an Beta phase. Docs, tests and even the code is not complete and may contain bugs.

Needservice directive

Use needservice to get the external data directly into your documentation.

.. needservice:: azure_config
   :query: [System.WorkItemType] = 'Issue'

Take a look into our needservice with Azure documentation for technical details.

.. needservice:: codebeamer_config
   :query: project.name IN ('my_project', 'another_project') and type = 'Requirement' and status = 'Draft'

Take a look into our needservice with Codebeamer documentation for technical details.

.. needservice:: jira_config
   :query: project = my_project

Take a look into our needservice with Jira documentation for technical details.

SNE script

The sne script provides solutions for different tasks like getting and storing external data or rendering templates.

Use sne import as command in your terminal to store external data in json files for later manipulation or for imports into your Sphinx project.

sne import azure_config --query "[System.WorkItemType] = 'Issue'"
sne import codebeamer_config --query "project.name IN ('my_project', 'another_project')"
sne import jira_config --query "project = my_project"

After this you can use sne render to create e.g. rst-files for your Sphinx project based on own templates.

sne render -j needs.json -t my_template.rst -o output.rst

See our docs about the sne script for more details.

Service configuration

Service names like jira_config are referencing a detailed configuration inside the conf.py file of a Sphinx project.

This configuration is shared by needservice and the sne script.

import os

# Manipulates the content to add a link to the source item
azure_content = f"""
Item URL: `{{data.fields["System.TeamProject"]}}/{{data.id}} <https://dev.azure.com/useblocks/{{data.fields["System.TeamProject"]}}/_workitems/edit/{{data.id}}>`_

.. raw:: html


needs_services = {
    "azure_config": {
        "url": "https://dev.azure.com/useblocks",
        "token": os.getenv("NEEDS_AZURE", ""),
        "id_prefix": "AZURE_",
        "query": "[System.WorkItemType] = 'Issue'",
        "content": azure_content,
        "mappings": {
            "id": ["id"],
            "type": "spec",
            "title": ["fields", "System.Title"],
            "status": ["fields", "System.State"],
        "extra_data": {
            "Original Type": ["fields", "System.WorkItemType"],
            "Original Assignee": ["fields", "System.AssignedTo", "displayName"],

For technical details, please read the pages needservice with Azure and Common service configuration.

# Manipulates the content to add a link to the source issue
cb_content = """
`Codebeamer Link to Issue {{data.id}} <{{data.cb_server}}/issue/{{data.id}}>`_


needs_services = {
    "codebeamer_config": {
        "url": "",
        "user": "bond",
        "password": "007",
        "prefix": "CB_IMPORT_",
        "content": cb_content,
        "query": "project.name IN ('my_project', 'another_project') and type = 'Requirement' and status = 'Draft'",
        "mappings": {
            "type": "spec",
            "tags": "cb_import, example",
            "id": ["id"],
            "status": ["status", "name"],
            "title": ["name"],
        "extra_data": {
            "assignedBy": ["assignedTo", 0, "name"],
            "createdAt": ["createdAt"],
            "updated": ["modifiedAt"],
            "type": ["typeName"],

For technical details, please read the pages needservice with Codebeamer and Common service configuration.

jira_content = """

needs_services = {
    "jira_config": {
        "url": "",
        "user": "test",
        "password": "test",
        "id_prefix": "JIRA_",
        "query": "project = PX",
        "content": jira_content,
        "mappings": {
            "id": ["key"],
            "type": "spec",
            "title": ["fields", "summary"],
            "status": ["fields", "status", "name"],
        "extra_data": {
            "Original Type": ["fields", "issuetype", "name"],
            "Original Assignee": ["fields", "assignee", "displayName"],

For technical details, please read the pages needservice with Jira and Common service configuration.


Sphinx-Needs Enterprise is free to use for private projects.

Commercial projects must obtain a commercial license, which guarantees an ongoing and professional development of Sphinx-Needs and related extensions. For details please see License.

Sphinx-Needs Ecosystem

In the last years additional information and extensions have been created, which are based or related to Sphinx-Needs:



Webpage to present most important Sphinx-Needs functions and related extensions.

Good entrypoint to understand the benefits and to get an idea about the complete ecosystem of Sphinx-Needs.



Base extension, which provides all of its functionality under the MIT license for free.

Create, update, link, filter and present need objects like Requirements, Specifications, Bugs and much more.


Sphinx-Needs Enterprise

Synchronizes Sphinx-Needs data with external, company internal systems like CodeBeamer, Jira or Azure Boards.

Provides scripts to baseline data and make CI usage easier.



Extension to import test results from xml files as need objects.

Created need objects can be filtered and e.g. linked to specification objects.

Further Sphinx extensions

During the work with Sphinx-Needs in bigger, company internal projects, other Sphinx extensions have been created to support the work in teams of the automotive industry:


Extension to collect or generate files from different sources and include them into the Sphinx source folder.

Sources like git repositories, jinja based files or symlinks are supported.


Provides a Bazel domain in Sphinx documentations and allows the automated import of Bazel files and their documentation.