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.

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 .

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