Codebeamer¶

The Codebeamer service synchronizes data between codebeamer from Intland and the Requirement Engineering extension Sphinx-Needs from useblocks.

The implementation is based on the services mechanism of Sphinx-Needs.

The Codebeamer service allows retrieving external data during documentation build and creates 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.

Options¶

The following options can be used inside .. needservice:: Codebeamer and related directives.

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.

raw¶

If set to “True”, the description content gets presented inside a code-block and is not handled as rst-valid text anymore. Use it to avoid sphinx build errors, if the item description is based on wiki or Html syntax.

Default: False

wiki2html¶

If set to “True”, wiki-based item content gets transformed to HTML and is presented in a .. raw:: html directive.

Default: True

If raw is set as well, content gets transformed to HTML, but is presented inside a code-block.

wiki2html_id¶

Integer value to specify which project id to use when request wiki2html requests.

Default: 2

cb_request_delay_ms¶

Integer value to set a delay between wiki2html requests to the API.

Default: 0

debug¶

Use :debug: to see the data structure of Codebeamer’s responses.

Config¶

A Codebeamer service configuration must be created inside your conf.py file.

The following documentation describes service specific information for Codebeamer only.

endpoint¶

Default value for Codebeamer services is /rest/v3/items/query.

See also endpoint for more details.

url¶

Please see url for details.

ssl_cert_abspath¶

Specifies an absolute path to a folder containing for example a self signed certificate for the codebeamer URL.

Example¶

Inside your conf.py file:

# 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"],
        },
    }
}

Inside any rst file of your Sphinx project:

.. needservice:: codebeamer_config
    :query: project.name IN ('my_project', 'another_project')
    :prefix: CB_IMPORT

.. needtable::
   :filter: "CB_IMPORT" in id

Result