| Name | mlx.jira-traceability JSON |
| Version |
2.1.0
JSON |
| download |
| home_page | None |
| Summary | Sphinx plugin to create Jira tickets based on traceable items |
| upload_time | 2025-07-11 22:34:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
traceability
jira
sphinx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: https://opensource.org/licenses/Apache-2.0
:alt: Apache 2.0 License
.. image:: https://badge.fury.io/py/mlx.jira-traceability.svg
:target: https://badge.fury.io/py/mlx.jira-traceability
:alt: PyPI packaged release
.. image:: https://github.com/melexis/jira-traceability/actions/workflows/python-package.yml/badge.svg?branch=main
:target: https://github.com/melexis/jira-traceability/actions/workflows/python-package.yml
:alt: Build status
.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg
:target: https://github.com/melexis/jira-traceability/issues
:alt: Contributions welcome
============
Introduction
============
Sphinx plugin for creating Jira tickets based on traceable items that have been added by
`mlx.traceability <https://pypi.org/project/mlx.traceability/>`_. You can look at this module as an extension for
mlx.traceability.
=====
Usage
=====
--------------------
Jira Ticket Creation
--------------------
Jira tickets that are based on traceable items can be automatically created by the plugin. A ticket gets created only
for each item of which its ID **matches** the configured regular expression ``item_to_ticket_regex``.
Duplication of tickets is avoided by querying Jira first for existing tickets based on the Jira project and the
value of the ticket field configured by ``jira_field_id``. Below is an example configuration:
Configuration
=============
.. code-block:: python
extensions = [
'mlx.traceability',
'mlx.jira_traceability',
]
traceability_jira_automation = {
'api_endpoint': 'https://example.atlassian.com',
'username': 'abc@example.com',
'password': 'my_api_token',
'item_to_ticket_regex': r'ACTION-12345_ACTION_\d+',
'jira_field_id': 'summary',
'issue_type': 'Task',
'project_key_regex': r'ACTION-(?P<project>\d{5})_',
'project_key_prefix': 'MLX', # MLX12345 for example
'default_project': 'SWCC',
'relationship_to_parent': ('depends_on', r'MEETING-[\w_]+'),
'components': '[SW],[HW]',
'description_head': 'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\n\n',
'description_str_to_attr': {'<<file_name>>': 'docname'},
'warn_if_exists': False,
'errors_to_warnings': True,
'notify_watchers': False,
}
Jira Configuration
------------------
Jira Server
^^^^^^^^^^^
:api_endpoint: ``https://jira.example.com/jira``
:username: ``abc``
:password: ``my_password``
Jira Cloud
^^^^^^^^^^
:api_endpoint: ``https://example.atlassian.com``
:username: ``abc@example.com``
:password: ``my_api_token``
Plugin Configuration
--------------------
``project_key_regex`` can optionally be defined. This regular expression with a named group *project* is used to
extract a certain part of the item ID to determine the Jira project key. ``project_key_prefix`` can optionally be
defined to add a prefix to the match for ``project_key_regex``. Additionally, ``default_project`` defines the Jira
project key or id in case the regular expression doesn't come up with a match or hasn't been configured.
``item_to_ticket_regex`` defines the regular expression used to filter item IDs to be exported as Jira tickets.
A warning gets reported when a Jira ticket already exists. These warnings can be disabled by setting
``warn_if_exists`` to ``True``. Errors raised by Jira are converted to warnings by default. If you want these errors to
crash your build, you can set ``errors_to_warnings`` to a falsy value.
The item ID of a linked item can be added to the summary of the Jira ticket to create by specifying the relationship
to this item in the value for setting ``relationship_to_parent``. The value can be a list or tuple with the relationship
as the first element and the regular expression to match the linked item's ID as the second element.
This feature makes it possible to create a query link in advance to list all Jira tickets that are related to this
linked item.
A string can be added to the start of a ticket's description by configuring ``description_head``. If the item to create
a ticket for does not have a body, its caption will be used to build the ticket's description.
Watchers of a ticket can be notified about the creation of the ticket by setting ``notify_watchers`` to ``True``.
Note that this notification is only sent when the user to assign to the ticket is different from the default assignee
configured in Jira.
Attributes
==========
All attributes are optional and are defined in `the default configuration of mlx.traceability
<https://melexis.github.io/sphinx-traceability-extension/configuration.html#default-config>`_.
- *assignee* is used to assign a username to the Jira ticket.
- *effort* is used to set the original effort estimation field. On failure, it gets appended to the description field.
If the item for which to create a ticket has an item linked to it by a ``relationship_to_parent`` relationship,
the *attendees* attribute of this linked item should be a comma-separated list of usernames that get added as watchers
to the ticket.
Mapping of Strings to Item Attributes (advanced)
================================================
If you want to use the value of an attribute of a TraceableItem in the string value for the
``description_head`` setting, you can set the ``description_str_to_attr`` setting to a dictionary mapping the string you
want to have replaced to the attribute of the ``TraceableItem`` that should take its place. In the following example,
some placeholder text will get replaced by the document name the item is located in:
.. code-block:: python
'description_head': 'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\n\n',
'description_str_to_attr': {'<<file_name>>': 'docname'}
Raw data
{
"_id": null,
"home_page": null,
"name": "mlx.jira-traceability",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "traceability, jira, sphinx",
"author": null,
"author_email": "Jasper Craeghs <jce@melexis.com>",
"download_url": "https://files.pythonhosted.org/packages/cf/88/374a38034c4147378cadb5301918e01ac814f5cbf7e172246bb7c44a4acb/mlx_jira_traceability-2.1.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg\n :target: https://opensource.org/licenses/Apache-2.0\n :alt: Apache 2.0 License\n\n.. image:: https://badge.fury.io/py/mlx.jira-traceability.svg\n :target: https://badge.fury.io/py/mlx.jira-traceability\n :alt: PyPI packaged release\n\n.. image:: https://github.com/melexis/jira-traceability/actions/workflows/python-package.yml/badge.svg?branch=main\n :target: https://github.com/melexis/jira-traceability/actions/workflows/python-package.yml\n :alt: Build status\n\n.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg\n :target: https://github.com/melexis/jira-traceability/issues\n :alt: Contributions welcome\n\n============\nIntroduction\n============\n\nSphinx plugin for creating Jira tickets based on traceable items that have been added by\n`mlx.traceability <https://pypi.org/project/mlx.traceability/>`_. You can look at this module as an extension for\nmlx.traceability.\n\n=====\nUsage\n=====\n\n--------------------\nJira Ticket Creation\n--------------------\n\nJira tickets that are based on traceable items can be automatically created by the plugin. A ticket gets created only\nfor each item of which its ID **matches** the configured regular expression ``item_to_ticket_regex``.\nDuplication of tickets is avoided by querying Jira first for existing tickets based on the Jira project and the\nvalue of the ticket field configured by ``jira_field_id``. Below is an example configuration:\n\nConfiguration\n=============\n\n.. code-block:: python\n\n extensions = [\n 'mlx.traceability',\n 'mlx.jira_traceability',\n ]\n\n traceability_jira_automation = {\n 'api_endpoint': 'https://example.atlassian.com',\n 'username': 'abc@example.com',\n 'password': 'my_api_token',\n 'item_to_ticket_regex': r'ACTION-12345_ACTION_\\d+',\n 'jira_field_id': 'summary',\n 'issue_type': 'Task',\n 'project_key_regex': r'ACTION-(?P<project>\\d{5})_',\n 'project_key_prefix': 'MLX', # MLX12345 for example\n 'default_project': 'SWCC',\n 'relationship_to_parent': ('depends_on', r'MEETING-[\\w_]+'),\n 'components': '[SW],[HW]',\n 'description_head': 'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\\n\\n',\n 'description_str_to_attr': {'<<file_name>>': 'docname'},\n 'warn_if_exists': False,\n 'errors_to_warnings': True,\n 'notify_watchers': False,\n }\n\nJira Configuration\n------------------\n\nJira Server\n^^^^^^^^^^^\n\n:api_endpoint: ``https://jira.example.com/jira``\n:username: ``abc``\n:password: ``my_password``\n\n\nJira Cloud\n^^^^^^^^^^\n\n:api_endpoint: ``https://example.atlassian.com``\n:username: ``abc@example.com``\n:password: ``my_api_token``\n\nPlugin Configuration\n--------------------\n\n``project_key_regex`` can optionally be defined. This regular expression with a named group *project* is used to\nextract a certain part of the item ID to determine the Jira project key. ``project_key_prefix`` can optionally be\ndefined to add a prefix to the match for ``project_key_regex``. Additionally, ``default_project`` defines the Jira\nproject key or id in case the regular expression doesn't come up with a match or hasn't been configured.\n\n``item_to_ticket_regex`` defines the regular expression used to filter item IDs to be exported as Jira tickets.\nA warning gets reported when a Jira ticket already exists. These warnings can be disabled by setting\n``warn_if_exists`` to ``True``. Errors raised by Jira are converted to warnings by default. If you want these errors to\ncrash your build, you can set ``errors_to_warnings`` to a falsy value.\n\nThe item ID of a linked item can be added to the summary of the Jira ticket to create by specifying the relationship\nto this item in the value for setting ``relationship_to_parent``. The value can be a list or tuple with the relationship\nas the first element and the regular expression to match the linked item's ID as the second element.\nThis feature makes it possible to create a query link in advance to list all Jira tickets that are related to this\nlinked item.\n\nA string can be added to the start of a ticket's description by configuring ``description_head``. If the item to create\na ticket for does not have a body, its caption will be used to build the ticket's description.\n\nWatchers of a ticket can be notified about the creation of the ticket by setting ``notify_watchers`` to ``True``.\nNote that this notification is only sent when the user to assign to the ticket is different from the default assignee\nconfigured in Jira.\n\nAttributes\n==========\n\nAll attributes are optional and are defined in `the default configuration of mlx.traceability\n<https://melexis.github.io/sphinx-traceability-extension/configuration.html#default-config>`_.\n\n- *assignee* is used to assign a username to the Jira ticket.\n- *effort* is used to set the original effort estimation field. On failure, it gets appended to the description field.\n\nIf the item for which to create a ticket has an item linked to it by a ``relationship_to_parent`` relationship,\nthe *attendees* attribute of this linked item should be a comma-separated list of usernames that get added as watchers\nto the ticket.\n\nMapping of Strings to Item Attributes (advanced)\n================================================\n\nIf you want to use the value of an attribute of a TraceableItem in the string value for the\n``description_head`` setting, you can set the ``description_str_to_attr`` setting to a dictionary mapping the string you\nwant to have replaced to the attribute of the ``TraceableItem`` that should take its place. In the following example,\nsome placeholder text will get replaced by the document name the item is located in:\n\n.. code-block:: python\n\n 'description_head': 'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\\n\\n',\n 'description_str_to_attr': {'<<file_name>>': 'docname'}\n",
"bugtrack_url": null,
"license": null,
"summary": "Sphinx plugin to create Jira tickets based on traceable items",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/melexis/jira-traceability",
"Issues": "https://github.com/melexis/jira-traceability/issues",
"Repository": "https://github.com/melexis/jira-traceability"
},
"split_keywords": [
"traceability",
" jira",
" sphinx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4de5fbcb993efd720ac86c08e728d1367a2233a5dc5841312cc1a3cfb4dedc3b",
"md5": "1f757aa0193bffa345c489e4e3267471",
"sha256": "d511ce061dae109b6bee8f2c5b3efc776362ffa8978b1add2c72c12b1a7d60e9"
},
"downloads": -1,
"filename": "mlx_jira_traceability-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f757aa0193bffa345c489e4e3267471",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18150,
"upload_time": "2025-07-11T22:34:48",
"upload_time_iso_8601": "2025-07-11T22:34:48.846424Z",
"url": "https://files.pythonhosted.org/packages/4d/e5/fbcb993efd720ac86c08e728d1367a2233a5dc5841312cc1a3cfb4dedc3b/mlx_jira_traceability-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cf88374a38034c4147378cadb5301918e01ac814f5cbf7e172246bb7c44a4acb",
"md5": "7218e82573356e48dbe4dc0db5e1d84b",
"sha256": "35dc238254242ef46bcca0102f9f2f62d981465362cb1d9d9cb38e6b6243166b"
},
"downloads": -1,
"filename": "mlx_jira_traceability-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7218e82573356e48dbe4dc0db5e1d84b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24129,
"upload_time": "2025-07-11T22:34:50",
"upload_time_iso_8601": "2025-07-11T22:34:50.023285Z",
"url": "https://files.pythonhosted.org/packages/cf/88/374a38034c4147378cadb5301918e01ac814f5cbf7e172246bb7c44a4acb/mlx_jira_traceability-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 22:34:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "melexis",
"github_project": "jira-traceability",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "mlx.jira-traceability"
}
