Welcome¶
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.
Warning
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
{{data.fields["System.Description"]}}"""
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}}>`_
{{data.description}}"""
needs_services = {
"codebeamer_config": {
"url": "http://127.0.0.1:8080",
"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 = """
{{data.fields.description}}"""
needs_services = {
"jira_config": {
"url": "http://127.0.0.1:8081",
"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.
License¶
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:
Sphinx-Needs.com
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.
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.
Sphinx-Test-Reports
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.
Content¶
Contents: