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, Azure, 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 the 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 files, e.g. rst-files, for your Sphinx project based on your 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, we have created additional information and extensions, which are based on or related to Sphinx-Needs:



The website presents the essential Sphinx-Needs functions and related extensions.

Also, it is a good entry point to understand the benefits and get an idea about the complete ecosystem of Sphinx-Needs.



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

The base extension provides all of its functionality under the MIT license for free.


Sphinx-Needs Enterprise

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

Provides scripts to baseline data and makes CI usage easier.



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

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

Other Sphinx extensions

During the use of Sphinx-Needs in popular companies’ internal projects, we have created other Sphinx extensions to support the work of teams in the automotive industry:


Sphinx Collections

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

It supports sources like Git repositories, Jinja based files or symlinks.


Sphinx Bazel

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