Skip to content

Commit ea8c569

Browse files
committed
Escape RST special characters in JIRA issue text
The jira_fixed_issues/jira_known_issues directives splice live JIRA issue summary, resolution, and status text directly into generated RST table rows. An unescaped asterisk (or other RST inline markup character) in a JIRA ticket's title can break the sphinx-build. Escape backslash, *, `, _, and | before inserting this text so no JIRA content can no longer break the docs build. JIRA: DOCS-173 Change-Id: I93e1efbb22f4a764e28e317227257d2a4a765cd0 Assisted-by: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Ivan Hrasko <ivan.hrasko@pantheon.tech>
1 parent d11b6bd commit ea8c569

1 file changed

Lines changed: 20 additions & 4 deletions

File tree

‎docs/ext/odl-jira.py‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,22 @@ def format_versions(versions):
6767
result.sort()
6868
return ", ".join(result)
6969

70+
# Characters that start RST inline markup. Backslash must be escaped first,
71+
# otherwise the backslashes inserted for the other characters would
72+
# themselves be escaped.
73+
_RST_SPECIAL_CHARS = ['\\', '*', '`', '_', '|']
74+
75+
def escape_rst(text):
76+
"""
77+
Escape characters that have special meaning in RST inline markup, so
78+
that arbitrary text (e.g. a JIRA issue summary) can be safely embedded
79+
in generated RST source without being interpreted as markup.
80+
"""
81+
text = str(text)
82+
for char in _RST_SPECIAL_CHARS:
83+
text = text.replace(char, '\\' + char)
84+
return text
85+
7086
class JiraFixedIssuesDirective(Directive):
7187
"""
7288
JIRA Fixed Issues directive
@@ -106,8 +122,8 @@ def run(self):
106122
table.append(' :align: center')
107123
table.append(' :alt: %s' % issue.fields.issuetype.name)
108124
table.append(' - `%s <https://jira.opendaylight.org/browse/%s>`_' % (issue.key, issue.key))
109-
table.append(' - %s' % issue.fields.summary)
110-
table.append(' - %s' % issue.fields.resolution)
125+
table.append(' - %s' % escape_rst(issue.fields.summary))
126+
table.append(' - %s' % escape_rst(issue.fields.resolution))
111127
table.append(' - %s' % format_versions(issue.fields.fixVersions))
112128

113129
table.append('')
@@ -160,8 +176,8 @@ def run(self):
160176
table.append(' :align: center')
161177
table.append(' :alt: %s' % issue.fields.issuetype.name)
162178
table.append(' - `%s <https://jira.opendaylight.org/browse/%s>`_' % (issue.key, issue.key))
163-
table.append(' - %s' % issue.fields.summary)
164-
table.append(' - %s' % issue.fields.status)
179+
table.append(' - %s' % escape_rst(issue.fields.summary))
180+
table.append(' - %s' % escape_rst(issue.fields.status))
165181
table.append(' - %s' % format_versions(issue.fields.versions))
166182
table.append(' - %s' % format_versions(issue.fields.fixVersions))
167183

0 commit comments

Comments
 (0)