ubTrace // Connect

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.

ubConnect features are supporting the following services and tools:

../../_images/azuredevops-logo.png

BETA

needservice

ubconnect import

../../_images/codebeamer-logo.png

BETA

needservice

ubconnect import

../../_images/jira-logo.png

BETA

needservice

ubconnect import

../../_images/elasticsearch-logo.png

BETA

ubconnect export

ubConnect 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.

ubconnect script

The ubconnect script provides solutions for different tasks like getting and storing external data or rendering templates.

Use ubconnect import as command in your terminal to store external data in JSON files for later manipulation or for imports into your Sphinx project. 

ubconnect import azure_config --query "[System.WorkItemType] = 'Issue'"

ubconnect import codebeamer_config --query "project.name IN ('my_project', 'another_project')"

ubconnect import jira_config --query "project = my_project"

After this you can use ubconnect render to create files, e.g. rst-files, for your Sphinx project based on your templates. 

ubconnect render -j needs.json -t my_template.rst -o output.rst

See our docs about the ubTrace // Connect 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 ubconnect script. 

import os

# Manipulates the content to add a link to the source item
azure_content = """
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 .