Improve handling of empty markup parameters.

ansible-community · Jun 30, 2024 · 9cfc85a · 9cfc85a
1 parent 2a7e443
commit 9cfc85a
Show file tree

Hide file tree

Showing 13 changed files with 28 additions and 8 deletions.
diff --git a/changelogs/fragments/290-empty.yml 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -24,6 +24,7 @@ Synopsis
 
 - Foo bar.
 - See \ :literal:`foo\_param\_1` (of role `ns2.flatcol.foo <foo_role.rst>`__, entrypoint main)\  for a random role parameter reference. And \ :literal:`foo\_param\_2=42` (of role `ns2.flatcol.foo <foo_role.rst>`__, 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
@@ -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: