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 = 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
Item URL: test/1 <div>Some azure description<br> </div>Original Type: Issue
Original Assignee: Daniel Woste
|
ID |
Title |
Status |
Type |
---|---|---|---|
test issue |
Doing |
spec |