Skip to content

Commit 5842088

Browse files
felixfonteinfelixfontein
authored
Fix handling of empty markup parameters for RST. (#262)
1 parent 9f3abb7 commit 5842088

File tree

4 files changed

+58
-22
lines changed

4 files changed

+58
-22
lines changed

‎changelogs/fragments/262-rst.yml

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
bugfixes:
2+
- "Fix handling of empty markup parameters for RST (https://github.com/ansible-community/antsibull-docs-ts/pull/262)."

‎src/rst.spec.ts

+4-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ describe('quoteRST tests', (): void => {
2121
expect(quoteRST(' foo ', false, true)).toBe(' foo \\ ');
2222
});
2323
it('simple string, escape spacing', (): void => {
24-
expect(quoteRST(' foo ', true, true)).toBe('\\ foo \\ ');
24+
expect(quoteRST(' foo ', true, true, true)).toBe('\\ foo \\ ');
25+
});
26+
it('simple string, escape empty', (): void => {
27+
expect(quoteRST('', true, true, true)).toBe('\\ ');
2528
});
2629
it('more complex', (): void => {
2730
expect(quoteRST('\\<_>`*<_>*`\\')).toBe('\\\\\\<\\_\\>\\`\\*\\<\\_\\>\\*\\`\\\\');

‎src/rst.ts

+31-21
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,12 @@ import { RSTOptions, AllFormatOptions, mergeOpts } from './opts';
88
import { OptionNamePart, Paragraph, ReturnValuePart } from './dom';
99
import { addToDestination } from './format';
1010

11-
export function quoteRST(text: string, escape_starting_whitespace = false, escape_ending_whitespace = false): string {
11+
export function quoteRST(
12+
text: string,
13+
escape_starting_whitespace = false,
14+
escape_ending_whitespace = false,
15+
must_not_be_empty = false,
16+
): string {
1217
text = text.replace(/([\\<>_*`])/g, '\\$1');
1318

1419
if (escape_ending_whitespace && text.endsWith(' ')) {
@@ -17,6 +22,9 @@ export function quoteRST(text: string, escape_starting_whitespace = false, escap
1722
if (escape_starting_whitespace && text.startsWith(' ')) {
1823
text = '\\ ' + text;
1924
}
25+
if (must_not_be_empty && text === '') {
26+
text = '\\ ';
27+
}
2028
return text;
2129
}
2230

@@ -37,7 +45,7 @@ function formatAntsibullOptionLike(part: OptionNamePart | ReturnValuePart, role:
3745
result.push('=');
3846
result.push(part.value);
3947
}
40-
return `\\ :${role}:\`${quoteRST(result.join(''), true, true)}\`\\ `;
48+
return `\\ :${role}:\`${quoteRST(result.join(''), true, true, true)}\`\\ `;
4149
}
4250

4351
function formatPlainOptionLike(part: OptionNamePart | ReturnValuePart): string {
@@ -63,43 +71,45 @@ function formatPlainOptionLike(part: OptionNamePart | ReturnValuePart): string {
6371
value = `${value}=${part.value}`;
6472
}
6573
const pluginText = plugin.length ? ` (of ${plugin.join('')})` : '';
66-
const mainText = `:literal:\`${quoteRST(value, true, true)}\``;
74+
const mainText = `:literal:\`${quoteRST(value, true, true, true)}\``;
6775
return `\\ ${mainText}${pluginText}\\ `;
6876
}
6977

7078
const DEFAULT_FORMATTER: AllFormatOptions = {
71-
formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
72-
formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true)}\`\\ `,
73-
formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true)}\`\\ `,
79+
formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true, true)}\\ `,
80+
formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true, true)}\`\\ `,
81+
formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true, true)}\`\\ `,
7482
formatHorizontalLine: () => '\n\n.. raw:: html\n\n <hr>\n\n',
75-
formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true)}\`\\ `,
76-
formatLink: (part) => `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `,
77-
formatModule: (part) => `\\ :ref:\`${quoteRST(part.fqcn)} <ansible_collections.${part.fqcn}_module>\`\\ `,
78-
formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text)} <${part.ref}>\`\\ `,
83+
formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true, true)}\`\\ `,
84+
formatLink: (part) => (part.text === '' ? '' : `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `),
85+
formatModule: (part) =>
86+
`\\ :ref:\`${quoteRST(part.fqcn, true, true, true)} <ansible_collections.${part.fqcn}_module>\`\\ `,
87+
formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text, true, true, true)} <${part.ref}>\`\\ `,
7988
formatURL: (part) => `\\ ${encodeURI(part.url)}\\ `,
8089
formatText: (part) => quoteRST(part.text),
81-
formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
90+
formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true, true)}\`\\ `,
8291
formatOptionName: (part) => formatAntsibullOptionLike(part, 'ansopt'),
83-
formatOptionValue: (part) => `\\ :ansval:\`${quoteRST(part.value, true, true)}\`\\ `,
92+
formatOptionValue: (part) => `\\ :ansval:\`${quoteRST(part.value, true, true, true)}\`\\ `,
8493
formatPlugin: (part) =>
8594
`\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
8695
formatReturnValue: (part) => formatAntsibullOptionLike(part, 'ansretval'),
8796
};
8897

8998
const PLAIN_FORMATTER: AllFormatOptions = {
90-
formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true)}\\ `,
91-
formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true)}\`\\ `,
92-
formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true)}\`\\ `,
99+
formatError: (part) => `\\ :strong:\`ERROR while parsing\`\\ : ${quoteRST(part.message, true, true, true)}\\ `,
100+
formatBold: (part) => `\\ :strong:\`${quoteRST(part.text, true, true, true)}\`\\ `,
101+
formatCode: (part) => `\\ :literal:\`${quoteRST(part.text, true, true, true)}\`\\ `,
93102
formatHorizontalLine: () => '\n\n------------\n\n',
94-
formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true)}\`\\ `,
95-
formatLink: (part) => `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `,
96-
formatModule: (part) => `\\ :ref:\`${quoteRST(part.fqcn)} <ansible_collections.${part.fqcn}_module>\`\\ `,
97-
formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text)} <${part.ref}>\`\\ `,
103+
formatItalic: (part) => `\\ :emphasis:\`${quoteRST(part.text, true, true, true)}\`\\ `,
104+
formatLink: (part) => (part.text === '' ? '' : `\\ \`${quoteRST(part.text)} <${encodeURI(part.url)}>\`__\\ `),
105+
formatModule: (part) =>
106+
`\\ :ref:\`${quoteRST(part.fqcn, true, true, true)} <ansible_collections.${part.fqcn}_module>\`\\ `,
107+
formatRSTRef: (part) => `\\ :ref:\`${quoteRST(part.text, true, true, true)} <${part.ref}>\`\\ `,
98108
formatURL: (part) => `\\ ${encodeURI(part.url)}\\ `,
99109
formatText: (part) => quoteRST(part.text),
100-
formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true)}\`\\ `,
110+
formatEnvVariable: (part) => `\\ :envvar:\`${quoteRST(part.name, true, true, true)}\`\\ `,
101111
formatOptionName: (part) => formatPlainOptionLike(part),
102-
formatOptionValue: (part) => `\\ :literal:\`${quoteRST(part.value, true, true)}\`\\ `,
112+
formatOptionValue: (part) => `\\ :literal:\`${quoteRST(part.value, true, true, true)}\`\\ `,
103113
formatPlugin: (part) =>
104114
`\\ :ref:\`${quoteRST(part.plugin.fqcn)} <ansible_collections.${part.plugin.fqcn}_${part.plugin.type}>\`\\ `,
105115
formatReturnValue: (part) => formatPlainOptionLike(part),

‎test-vectors.yaml

+21
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,27 @@ test_vectors:
3434
ansible_doc_text: This is a `test' `module' *markup*.
3535
rst_plain: This is a \ :literal:`test`\ \ :emphasis:`module`\ \ :strong:`markup`\
3636
.
37+
empty_tags:
38+
source: |-
39+
C() I() B() C() U() L(,) R(,) V() O() RV() E()
40+
html: <p><code class='docutils literal notranslate'></code> <em></em> <b></b>
41+
<code class='docutils literal notranslate'></code> <a href=''></a> <a href=''></a>
42+
<span class='module'></span> <code class="ansible-value literal notranslate"></code>
43+
<code class="ansible-option literal notranslate"><strong></strong></code> <code
44+
class="ansible-return-value literal notranslate"></code> <code class="xref std
45+
std-envvar literal notranslate"></code></p>
46+
html_plain: <p><code></code> <em></em> <b></b> <code></code> <a href=''></a> <a
47+
href=''></a> <span></span> <code></code> <code><strong></strong></code> <code></code>
48+
<code></code></p>
49+
md: <code></code> <em></em> <b></b> <code></code> []() []() <code></code> <code><strong></strong></code>
50+
<code></code> <code></code>
51+
rst: '\ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \
52+
\ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`\ `\ \ :ansretval:`\ `\ \
53+
:envvar:`\ `\ '
54+
rst_plain: '\ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\
55+
`\ \ \ \ :ref:`\ <>`\ \ :literal:`\ `\ \ :literal:`\ `\ \ :literal:`\
56+
`\ \ :envvar:`\ `\ '
57+
ansible_doc_text: "`' `' ** `' <> `' `' `' `'"
3758
module:
3859
source: |-
3960
The M(a.b.c) module.

0 commit comments

Comments
 (0)