From: Robert Varga Date: Thu, 22 Oct 2020 11:23:21 +0000 (+0200) Subject: Extract JIRA issues X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=b48ec16bfdafddae3b154a4b295cde63ba8d4b73;p=docs.git Extract JIRA issues We want to capture a table of JIRA issues for a number of MRI project versions. Nothing in upstream fits the bill, so we introduce our own Sphinx extension, which uses the jira module to extract information from JIRA and embed it into our RTD site. Since there is no spell checker running on JIRA, we exclude files in release-notes/projects/ from the Sphinx spell checker. Change-Id: I5b0ac293dca2442776753078dbd1c79a52684677 Signed-off-by: Robert Varga --- diff --git a/docs/conf.py b/docs/conf.py index bb48fddb1..7d526ac42 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,6 +11,7 @@ ############################################################################## from docs_conf.conf import * +import sys, os # Append to intersphinx_mapping intersphinx_mapping['aaa'] = ('https://docs.opendaylight.org/projects/aaa/en/latest/', None) @@ -81,11 +82,15 @@ nitpicky = True release = version spelling_warning = True -spelling_exclude_patterns = ['release-notes/release-notes-*'] +spelling_exclude_patterns = ['release-notes/release-notes-*', 'release-notes/projects/*'] html_context = { 'version_status': 'supported', } +# Helper for JIRA references +sys.path.append(os.path.abspath('ext')) +extensions.append('odl-jira') + def setup(app): app.add_css_file("css/ribbon.css") diff --git a/docs/ext/README.md b/docs/ext/README.md new file mode 100644 index 000000000..a7b18f33e --- /dev/null +++ b/docs/ext/README.md @@ -0,0 +1,3 @@ +Sphinx extensions + +TODO: add proper linking diff --git a/docs/ext/odl-jira.py b/docs/ext/odl-jira.py new file mode 100644 index 000000000..400eba893 --- /dev/null +++ b/docs/ext/odl-jira.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +# Copyright (c) 2021 PANTHEON.tech, s.r.o. and others. All rights reserved. +# +# This program and the accompanying materials are made available under the +# terms of the Eclipse Public License v1.0 which accompanies this distribution, +# and is available at http://www.eclipse.org/legal/epl-v10.html +""" + +Embeds a simple table with issues. + +""" + +from docutils import nodes +from docutils.parsers.rst import directives, Directive +from jira import JIRA +import re +import sphinx + +__copyright__ = "Copyright(c) 2021 PANTHEON.tech, s.r.o." +__license__ = "Eclipse Public License v1.0" + +class JiraFixedIssuesDirective(Directive): + """ + JIRA Fixed Issues directive + """ + has_content = True + required_arguments = 0 + optional_arguments = 0 + + option_spec = { + "project": directives.unchanged_required, + "versions": directives.unchanged_required, + } + + def run(self): + jira = JIRA(server="https://jira.opendaylight.org") + prj = jira.project(self.options.get('project')) + (from_ver, to_ver) = self.options.get('versions').split('-', 1) + + versions = set() + for ver in jira.project_versions(prj): + if ver.name >= from_ver and ver.name <= to_ver: + versions.add(ver.name) + versions = ", ".join(versions) + + # FIXME: this is not quite nice: can we emit the table markup directly + table = [ + '.. list-table:: Issues resolved in versions %s through %s' % (from_ver, to_ver), + # FIXME: bind to https://datatables.net/ + ' :class: datatable', + ' :header-rows: 1', + ' :widths: auto', + '', + ' * - Type', + ' - Key', + ' - Summary', + ' - Resolution', + ' - Fix Version(s)', + ] + + issues = jira.search_issues('project = %s AND resolution is not EMPTY AND fixVersion in (%s) ORDER BY type ASC' % (prj, versions)) + for issue in issues: + # Groom fixVersions + fixVersions = set() + for version in issue.fields.fixVersions: + fixVersions.add(version.name) + fixVersions = list(fixVersions) + fixVersions.sort() + + table.append(' * - .. image:: %s' % issue.fields.issuetype.iconUrl) + table.append(' :align: center') + table.append(' :alt: %s' % issue.fields.issuetype.name) + table.append(' - `%s `_' % (issue.key, issue.key)) + table.append(' - %s' % issue.fields.summary) + table.append(' - %s' % issue.fields.resolution) + table.append(' - %s' % ", ".join(fixVersions)) + + table.append('') + + for idx, line in enumerate(table): + self.content.data.insert(idx, line) + self.content.items.insert(idx, (None, idx)) + + node = nodes.container() + self.state.nested_parse(self.content, self.content_offset, node) + return node.children + +class JiraKnownIssuesDirective(Directive): + """ + JIRA Known Issues directive + """ + has_content = True + required_arguments = 0 + optional_arguments = 0 + + option_spec = { + "project": directives.unchanged_required, + "versions": directives.unchanged_required, + } + + def run(self): + jira = JIRA(server="https://jira.opendaylight.org") + prj = jira.project(self.options.get('project')) + (from_ver, to_ver) = self.options.get('versions').split('-', 1) + + versions = set() + for ver in jira.project_versions(prj): + if ver.name >= from_ver and ver.name <= to_ver: + versions.add(ver.name) + versions = ", ".join(versions) + + # FIXME: this is not quite nice: can we emit the table markup directly + table = [ + '.. list-table:: Issues affecting versions %s through %s' % (from_ver, to_ver), + # FIXME: bind to https://datatables.net/ + ' :class: datatable', + ' :header-rows: 1', + ' :widths: auto', + '', + ' * - Type', + ' - Key', + ' - Summary', + ' - Status', + ' - Affected Version(s)', + ' - Fix Version(s)', + ] + + issues = jira.search_issues('project = %s AND affectedVersion in (%s) AND fixVersion NOT in (%s) ORDER BY type ASC' % (prj, versions, versions)) + for issue in issues: + # Groom fixVersions + fixVersions = set() + for version in issue.fields.fixVersions: + fixVersions.add(version.name) + fixVersions = list(fixVersions) + fixVersions.sort() + + # Groom affectedVersions + affectedVersions = set() + for version in issue.fields.versions: + affectedVersions.add(version.name) + affectedVersions = list(affectedVersions) + affectedVersions.sort() + + table.append(' * - .. image:: %s' % issue.fields.issuetype.iconUrl) + table.append(' :align: center') + table.append(' :alt: %s' % issue.fields.issuetype.name) + table.append(' - `%s `_' % (issue.key, issue.key)) + table.append(' - %s' % issue.fields.summary) + table.append(' - %s' % issue.fields.status) + table.append(' - %s' % ", ".join(affectedVersions)) + table.append(' - %s' % ", ".join(fixVersions)) + + table.append('') + + for idx, line in enumerate(table): + self.content.data.insert(idx, line) + self.content.items.insert(idx, (None, idx)) + + node = nodes.container() + self.state.nested_parse(self.content, self.content_offset, node) + return node.children + +def setup(app): + """ + :type app: sphinx.application.Sphinx + """ + app.add_directive('jira_fixed_issues', JiraFixedIssuesDirective) + app.add_directive('jira_known_issues', JiraKnownIssuesDirective) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } + diff --git a/docs/release-notes/projects/controller.rst b/docs/release-notes/projects/controller.rst index 0fbe8c87b..c891f289a 100644 --- a/docs/release-notes/projects/controller.rst +++ b/docs/release-notes/projects/controller.rst @@ -9,12 +9,6 @@ The Controller project is an infrastructure service that supports other OpenDayl It does not have user-facing features. -Changes in Phosphorus release stream -==================================== -There is a comprehensive list of JIRA issues -`resolved in this release `__ - - Behavior/Feature Changes ======================== @@ -36,9 +30,21 @@ There are no deprecated features in this release, but there is a large number of * prefix-based shards have been completely removed * the proof-of-concept ``messagebus`` component was removed +Resolved Issues +=============== + +The following table lists the issues resolved in this release. + +.. jira_fixed_issues:: + :project: CONTROLLER + :versions: 4.0.0-4.0.3 + Known Issues ============ -Here is the link to the known issues exist in this release: +The following table lists the known issues that exist in this release. + +.. jira_known_issues:: + :project: CONTROLLER + :versions: 4.0.0-4.0.3 -`OpenDaylight JIRA Tickets - Known Issue `_ diff --git a/docs/requirements.txt b/docs/requirements.txt index a92da717a..dd1e40f76 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ lfdocs-conf>0.6.1 +jira