diff --git a/changelogs/fragments/290-empty.yml b/changelogs/fragments/290-empty.yml new file mode 100644 index 00000000..5e0d973c --- /dev/null +++ b/changelogs/fragments/290-empty.yml @@ -0,0 +1,4 @@ +bugfixes: + - "Improve handling of empty markup parameters for RST (https://github.com/ansible-community/antsibull-docs/pull/290)." +minor_changes: + - "Bump minimum dependency of ``antsibull-docs-parser`` to 1.0.2 or newer (https://github.com/ansible-community/antsibull-docs/pull/290)." diff --git a/pyproject.toml b/pyproject.toml index b5ee2d04..37dfa47a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,7 +28,7 @@ dependencies = [ "ansible-pygments", "antsibull-changelog >= 0.24.0", "antsibull-core >= 2.1.0, < 4.0.0", - "antsibull-docs-parser >= 1.0.0, < 2.0.0", + "antsibull-docs-parser >= 1.0.2, < 2.0.0", "asyncio-pool", "docutils", "jinja2 >= 3.0", diff --git a/src/antsibull_docs/markup/rstify.py b/src/antsibull_docs/markup/rstify.py index deceb429..206b8647 100644 --- a/src/antsibull_docs/markup/rstify.py +++ b/src/antsibull_docs/markup/rstify.py @@ -46,8 +46,14 @@ def __init__(self, referable_envvars: set[str] | None = None): def format_env_variable(self, part: dom.EnvVariablePart) -> str: envvar = part.name.split("=", 1)[0].strip() if envvar in self._referable_envvars: - return f"\\ :ansenvvarref:`{_rst_escape(part.name, True)}`\\ " - return f"\\ :ansenvvar:`{_rst_escape(part.name, True)}`\\ " + text = _rst_escape( + part.name, escape_ending_whitespace=True, must_not_be_empty=True + ) + return f"\\ :ansenvvarref:`{text}`\\ " + text = _rst_escape( + part.name, escape_ending_whitespace=True, must_not_be_empty=True + ) + return f"\\ :ansenvvar:`{text}`\\ " class SimplifiedRSTLinkProvider(LinkProvider): diff --git a/tests/functional/ansible-doc-cache-all-others.json b/tests/functional/ansible-doc-cache-all-others.json index 8d3bab67..303109f4 100644 --- a/tests/functional/ansible-doc-cache-all-others.json +++ b/tests/functional/ansible-doc-cache-all-others.json @@ -23329,7 +23329,8 @@ "collection": "ns2.flatcol", "description": [ "Foo bar.", - "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value." + "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value.", + "C() I() B() C() U() L(,) R(,) V() O() RV() E()" ], "filename": "ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py", "has_action": false, diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json index 7b5bd6fd..f1929273 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -23246,7 +23246,8 @@ "collection": "ns2.flatcol", "description": [ "Foo bar.", - "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value." + "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value.", + "C() I() B() C() U() L(,) R(,) V() O() RV() E()" ], "filename": "ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py", "has_action": false, diff --git a/tests/functional/ansible-doc-cache-ansible.builtin-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.flatcol.json index 63f564e0..3c95a731 100644 --- a/tests/functional/ansible-doc-cache-ansible.builtin-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ansible.builtin-ns2.flatcol.json @@ -22167,7 +22167,8 @@ "collection": "ns2.flatcol", "description": [ "Foo bar.", - "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value." + "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value.", + "C() I() B() C() U() L(,) R(,) V() O() RV() E()" ], "filename": "ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py", "has_action": false, diff --git a/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json index 20678f43..f8a0d7fb 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json @@ -1856,7 +1856,8 @@ "collection": "ns2.flatcol", "description": [ "Foo bar.", - "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value." + "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value.", + "C() I() B() C() U() L(,) R(,) V() O() RV() E()" ], "filename": "ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py", "has_action": false, diff --git a/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json index dc249d36..3bd055cd 100644 --- a/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json +++ b/tests/functional/ansible-doc-cache-ns.col1-ns2.col-ns2.flatcol.json @@ -1477,7 +1477,8 @@ "collection": "ns2.flatcol", "description": [ "Foo bar.", - "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value." + "See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value.", + "C() I() B() C() U() L(,) R(,) V() O() RV() E()" ], "filename": "ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py", "has_action": false, diff --git a/tests/functional/baseline-default/collections/ns2/flatcol/foo2_module.rst b/tests/functional/baseline-default/collections/ns2/flatcol/foo2_module.rst index aa315708..e13b614a 100644 --- a/tests/functional/baseline-default/collections/ns2/flatcol/foo2_module.rst +++ b/tests/functional/baseline-default/collections/ns2/flatcol/foo2_module.rst @@ -50,6 +50,7 @@ Synopsis - Foo bar. - See \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_1`\ for a random role parameter reference. And \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_2=42`\ for one with a value. +- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`ns2.flatcol.foo2#module:`\ \ :ansretval:`ns2.flatcol.foo2#module:`\ \ :ansenvvar:`\ `\ .. Aliases diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo2_module.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo2_module.rst index aa315708..e13b614a 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo2_module.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/flatcol/foo2_module.rst @@ -50,6 +50,7 @@ Synopsis - Foo bar. - See \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_1`\ for a random role parameter reference. And \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_2=42`\ for one with a value. +- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`ns2.flatcol.foo2#module:`\ \ :ansretval:`ns2.flatcol.foo2#module:`\ \ :ansenvvar:`\ `\ .. Aliases diff --git a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo2_module.rst b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo2_module.rst index aa315708..e13b614a 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo2_module.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/flatcol/foo2_module.rst @@ -50,6 +50,7 @@ Synopsis - Foo bar. - See \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_1`\ for a random role parameter reference. And \ :ansopt:`ns2.flatcol.foo#role:main:foo\_param\_2=42`\ for one with a value. +- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`ns2.flatcol.foo2#module:`\ \ :ansretval:`ns2.flatcol.foo2#module:`\ \ :ansenvvar:`\ `\ .. Aliases diff --git a/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/foo2_module.rst b/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/foo2_module.rst index 0472337d..bf18a333 100644 --- a/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/foo2_module.rst +++ b/tests/functional/baseline-simplified-rst/collections/ns2/flatcol/foo2_module.rst @@ -24,6 +24,7 @@ Synopsis - Foo bar. - See \ :literal:`foo\_param\_1` (of role `ns2.flatcol.foo `__, entrypoint main)\ for a random role parameter reference. And \ :literal:`foo\_param\_2=42` (of role `ns2.flatcol.foo `__, entrypoint main)\ for one with a value. +- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :literal:`\ `\ \ :literal:`` (`link <#parameter->`_)\ \ :literal:`` (`link <#return->`_)\ \ :literal:``\ diff --git a/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py b/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py index 45a509e4..09c09b59 100644 --- a/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py +++ b/tests/functional/collections/ansible_collections/ns2/flatcol/plugins/modules/sub/foo2.py @@ -18,6 +18,7 @@ - Foo bar. - See O(ns2.flatcol.foo#role:main:foo_param_1) for a random role parameter reference. And O(ns2.flatcol.foo#role:main:foo_param_2=42) for one with a value. + - C() I() B() C() U() L(,) R(,) V() O() RV() E() options: bar: description: