Azure¶

The Azure service synchronizes data between Azure DevOps Boards/WorkItems and the life cycle management extension Sphinx-Needs from useblocks.

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

The Azure service allows you to retrieve 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:: Azure and related directives.

query¶

A query string, which must be valid to WIQL.

prefix¶

A string, which is taken as prefix for the need-id. E.g. AZURE_IMPORT –> AZURE_IMPORT_001.

Config¶

An Azure service configuration must be created inside your conf.py file.

The following documentation describes service - specific information for Azure only.

url¶

The url should look like``https://dev.azure.com/<company>”, where ``<company> must be replaced.

Please see url for more details.

token¶

Instead of a user and a password, Azure DevOps needs a personal access token.

You can create a personal access token under https://dev.azure.com/<company>/_usersSettings/tokens.

Example¶

Inside your conf.py file:

import os

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

Inside any rst file of your Sphinx project:

.. needservice:: azure_config
    :query: [System.WorkItemType] = 'Issue'
    :prefix: AZURE_IMPORT_

.. needtable::
    :filter: "AZURE_IMPORT" in id
    :columns: id, title, status, type
    :style: table

Result

Specification: test issue AZURE_IMPORT_1

status: Doing

Item URL: test/1 <div>Some azure description<br> </div> Original Type: Issue Original Assignee: Daniel Woste