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.

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 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 = """
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