Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve handling of empty markup parameters; make linter aware of these #290

Merged
merged 1 commit into from
Jun 30, 2024
Merged

Improve handling of empty markup parameters; make linter aware of these #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions changelogs/fragments/290-empty.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)."
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
10 changes: 8 additions & 2 deletions src/antsibull_docs/markup/rstify.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
3 changes: 2 additions & 1 deletion tests/functional/ansible-doc-cache-all-others.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22712,7 +22712,8 @@
"The option O(foo) exists, but O(foobar) does not.",
"The return value RV(bar) exists, but RV(barbaz) does not.",
"Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)",
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)",
"C() I() B() C() U() L(,) R(,) V() O() RV() E()"
],
"filename": "ansible_collections/ns/col2/plugins/modules/foo2.py",
"has_action": false,
Expand Down
3 changes: 2 additions & 1 deletion tests/functional/ansible-doc-cache-all.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22629,7 +22629,8 @@
"The option O(foo) exists, but O(foobar) does not.",
"The return value RV(bar) exists, but RV(barbaz) does not.",
"Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)",
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)",
"C() I() B() C() U() L(,) R(,) V() O() RV() E()"
],
"filename": "ansible_collections/ns/col2/plugins/modules/foo2.py",
"has_action": false,
Expand Down
3 changes: 2 additions & 1 deletion tests/functional/ansible-doc-cache-ansible.builtin-ns.col2-ns2.col.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22629,7 +22629,8 @@
"The option O(foo) exists, but O(foobar) does not.",
"The return value RV(bar) exists, but RV(barbaz) does not.",
"Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)",
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)",
"C() I() B() C() U() L(,) R(,) V() O() RV() E()"
],
"filename": "ansible_collections/ns/col2/plugins/modules/foo2.py",
"has_action": false,
Expand Down
3 changes: 2 additions & 1 deletion tests/functional/ansible-doc-cache-ns.col1-ns.col2-ns2.col-ns2.flatcol.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1239,7 +1239,8 @@
"The option O(foo) exists, but O(foobar) does not.",
"The return value RV(bar) exists, but RV(barbaz) does not.",
"Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)",
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)",
"C() I() B() C() U() L(,) R(,) V() O() RV() E()"
],
"filename": "ansible_collections/ns/col2/plugins/modules/foo2.py",
"has_action": false,
Expand Down
3 changes: 2 additions & 1 deletion tests/functional/ansible-doc-cache-ns.col2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -804,7 +804,8 @@
"The option O(foo) exists, but O(foobar) does not.",
"The return value RV(bar) exists, but RV(barbaz) does not.",
"Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)",
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
"Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)",
"C() I() B() C() U() L(,) R(,) V() O() RV() E()"
],
"filename": "ansible_collections/ns/col2/plugins/modules/foo2.py",
"has_action": false,
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-default/collections/ns/col2/foo2_module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ Synopsis
- The return value \ :ansretval:`ns.col2.foo2#module:bar`\ exists, but \ :ansretval:`ns.col2.foo2#module:barbaz`\ does not.
- Again existing: \ :ansopt:`ns.col2.foo#module:foo=1`\ , \ :ansretval:`ns.col2.foo#module:bar=2`\
- Again not existing: \ :ansopt:`ns.col2.foo#module:foobar=1`\ , \ :ansretval:`ns.col2.foo#module:barbaz=2`\
- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`ns.col2.foo2#module:`\ \ :ansretval:`ns.col2.foo2#module:`\ \ :ansenvvar:`\ `\


.. Aliases
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-no-breadcrumbs/collections/ns/col2/foo2_module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ Synopsis
- The return value \ :ansretval:`ns.col2.foo2#module:bar`\ exists, but \ :ansretval:`ns.col2.foo2#module:barbaz`\ does not.
- Again existing: \ :ansopt:`ns.col2.foo#module:foo=1`\ , \ :ansretval:`ns.col2.foo#module:bar=2`\
- Again not existing: \ :ansopt:`ns.col2.foo#module:foobar=1`\ , \ :ansretval:`ns.col2.foo#module:barbaz=2`\
- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :ansval:`\ `\ \ :ansopt:`ns.col2.foo2#module:`\ \ :ansretval:`ns.col2.foo2#module:`\ \ :ansenvvar:`\ `\


.. Aliases
Expand Down
1 change: 1 addition & 0 deletions tests/functional/baseline-simplified-rst/collections/ns/col2/foo2_module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Synopsis
- The return value \ :literal:`bar` (`link <#return-bar>`_)\ exists, but \ :literal:`barbaz` (`link <#return-barbaz>`_)\ does not.
- Again existing: \ :literal:`foo=1` (of module `ns.col2.foo <foo_module.rst>`__)\ , \ :literal:`bar=2` (of module `ns.col2.foo <foo_module.rst>`__)\
- Again not existing: \ :literal:`foobar=1` (of module `ns.col2.foo <foo_module.rst>`__)\ , \ :literal:`barbaz=2` (of module `ns.col2.foo <foo_module.rst>`__)\
- \ :literal:`\ `\ \ :emphasis:`\ `\ \ :strong:`\ `\ \ :literal:`\ `\ \ \ \ :ref:`\ <>`\ \ :literal:`\ `\ \ :literal:`` (`link <#parameter->`_)\ \ :literal:`` (`link <#return->`_)\ \ :literal:``\



Expand Down
1 change: 1 addition & 0 deletions tests/functional/collections/ansible_collections/ns/col2/plugins/modules/foo2.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
- The return value RV(bar) exists, but RV(barbaz) does not.
- "Again existing: O(ns.col2.foo#module:foo=1), RV(ns.col2.foo#module:bar=2)"
- "Again not existing: O(ns.col2.foo#module:foobar=1), RV(ns.col2.foo#module:barbaz=2)"
- C() I() B() C() U() L(,) R(,) V() O() RV() E()
options:
foo:
description: The foo source.
Expand Down
14 changes: 14 additions & 0 deletions tests/functional/test_docs_linting.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -288,6 +290,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -371,6 +375,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -462,6 +468,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -588,6 +596,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -696,6 +706,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down Expand Up @@ -802,6 +814,8 @@ def test_docsite_linting_failure(tmp_path_factory):
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[5]: RV(ns.col2.foo#module:bar=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: O(ns.col2.foo#module:foobar=1): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[6]: RV(ns.col2.foo#module:barbaz=2): there is no module ns.col2.foo",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: O(): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> description[7]: RV(): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> bar -> description[2]: O(broken markup): option name does not reference to an existing option of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> options -> subfoo -> suboptions -> foo -> description[4]: RV(foobarbaz): return value name does not reference to an existing return value of the module ns.col2.foo2",
"plugins/modules/foo2.py:0:0: DOCUMENTATION -> seealso[2]: there is no module ns.col2.foobarbaz",
Expand Down