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, 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.
Warning
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
{{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, we have created additional information and extensions, which are based on or related to Sphinx-Needs:
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:
