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.

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.

Hint

For details about most configuration options, please take a look into the common configuration description.

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.

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

Hint

The below are examples of just images, since no Codebeamer instance was available during documentation build.

../_images/cb_example.png ../_images/cb_table.png