Needs service
Sphinx-Needs-Codebeamer
uses the services mechanism of
Sphinx-Needs.
This allows to retrieve external data during documentation build and create Sphinx-Needs objects based on this data.
After the created Sphinx-Needs objects support every function from
Sphinx-Needs, which includes Filtering, Linking,
Updating and much more.
Example:
Inside any rst
file of your Sphinx project:
.. needservice:: codebeamer
:query: project.name IN ('my_project', 'another_project')
:prefix: MY_IMPORT_
- query
A query string, which must be valid to cbQL.
- prefix
A string, which is taken as prefix for the need-id. E.g. CB_IMPORT_
–> CB_IMPORT_005
.
You must also create a codebeamer service configuration in your conf.py
file.
my_content = """
Issues content:
{{description}}
"""
needs_services = {
'codebeamer': {
'url': 'https://my_codebeamer.com',
'id_prefix': 'CB_',
'mapping': {
'type': ['typeName'],
'id': ['id'],
'title': ['name'],
},
'mapping_replaces': {
'^Task$': 'task',
'^Requirement$': 'req',
'^Specification$': 'spec',
},
'content': my_content,
'extra_data': {
'assignedBy': ['assignedTo', 0, 'name'],
'createdAt': ['createdAt'],
}
}
}
{% rawend %}
URL
of the server. The final REST
api location gets added automatically. which is by default
/rest/v3/items/query
.
A prefix for the final ID of the created need.
Can get important, if the IDs from Codebeamer are not unique.
Example: CB_
will create IDs like CB_1002
.
Field names from Codebeamer do normally not map to option names of Sphinx-Needs.
So mapping
defines, from where a Sphinx-Needs option shall get its value inside the Codebeamer data.
mapping
must be a dictionary, where the key is the needs object name and the value is a list or tuple,
which defines the location of the value in the retrieved Codebeamer data object.
Example
Goal: The need option author
shall be set to the Assignee name.
This information is stored in the retrieved Codebeamer json data under assignedTo.0.name
.
So the final mapping
entry looks like:
'mapping': {
'author': ['assignedTo', 0, 'name'],
}
Note: Mapping data from multiple locations, e.g. because asssignedTo
contains is list,
is currently not supported.
There are use cases, where a value inside Codebeamer data is not valid for a Sphinx-Needs options.
For instance: In Codebeamer the type is named Requirement
, but Sphinx-Needs supports only req
as value
for type
option.
mappings_replaces
can replace strings defined by a regular expression with a new value.
This replacement is performed for all mappings.
Example
The Codebeamer value Requirement
must be replaced by req
and set as value for the need option type
.
'codebeamer': {
'mapping': {
'type': ['typeName'], # maps the original location
},
'mapping_replaces': {
'^Requirement$': 'req',
}
}
{% raw %}
content
takes a string, which gets interpreted as rst-code for the need-content area.
Jinja support is also available, so that data retrieved from Codebeamer is available and can be accessed like
{{description}}
.
Example:
needs_services = {
'content': """
Content from Codebeamer Issue
-----------------------------
``{{description}}``.
This is assigned to **{{assignedTo[0].name]}}**``.
`Link to source <http://my_server/issue/{{id}}>`_
"""
}
conf.py
needs_services = {
'codebeamer': {
'url': "http://127.0.0.1:8080",
'prefix': "CB_IMPORT_",
'mapping': {
'id': ['id'],
'type': ['typeName'],
'status': ['status', 'name'],
'title': ['name'],
'author': ['createdBy', 'name'],
},
'mapping_replaces': {
'^Task$': 'task',
'^Requirement$': 'req',
'^Specification$': 'spec',
},
'extra_data': {
'assignedBy': ['assignedTo', 0, 'name'],
'createdAt': ['createdAt'],
'updated': ['modifiedAt'],
}
}
}
Any rst file
.. needservice:: codebeamer
:query: project.name IN ('my_project', 'another_project')
:prefix: CB_IMPORT
Result
Hint
The below examples are just images, as no CodeBeamer instance is available on ReadTheDocs to generate this
data during build phase.
.. needtable::
:filter: "CB_IMPORT" in id