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 to retrieve external data during documentation build and to create 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.

Hint

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

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 need a personal access token.

Which can be created 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 ../_images/arrow-right-circle.svg
status: Doing

Item URL: test/1

Some azure description

Original Type: Issue
Original Assignee: Daniel Woste

ID

Title

Status

Type

AZURE_IMPORT_1

test issue

Doing

spec