From f585f6de32cecaad2b3345523b41ea4ec906b9fc Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 9 Jun 2023 06:13:45 +0200 Subject: [PATCH 1/2] Fix deprecations for plugins and role entrypoints (#156) * Fix indent of 'Why' and 'Alternative' texts. * Add tests. * Allow role entrypoint deprecations without having to specify the collection the role is removed from. * Fix YAML. * Fix typo. Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> --------- Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> (cherry picked from commit 2d3c65e2d3d5af7bd5e9c6af41b3007c6f7161c5) --- .../fragments/156-indent-deprecation.yml | 3 ++ src/antsibull_docs/data/docsite/plugin.rst.j2 | 4 +-- src/antsibull_docs/data/docsite/role.rst.j2 | 4 +-- src/antsibull_docs/schemas/docs/role.py | 20 +++++++++++++ tests/functional/ansible-doc-cache-all.json | 15 ++++++++-- .../functional/ansible-doc-cache-ns2.col.json | 15 ++++++++-- .../collections/ns2/col/foo_become.rst | 26 ++++++++++++++++ .../collections/ns2/col/foo_role.rst | 11 +++++++ .../collections/ns2/col/foo_become.rst | 26 ++++++++++++++++ .../collections/ns2/col/foo_role.rst | 11 +++++++ .../collections/ns2/col/foo_become.rst | 26 ++++++++++++++++ .../collections/ns2/col/foo_role.rst | 11 +++++++ .../baseline-squash-hierarchy/foo_become.rst | 26 ++++++++++++++++ .../baseline-squash-hierarchy/foo_role.rst | 11 +++++++ .../collections/ns2/col/foo_become.rst | 30 +++++++++++++++++-- .../collections/ns2/col/foo_role.rst | 11 +++++++ .../ns2/col/meta/runtime.yml | 7 +++++ .../ns2/col/plugins/become/foo.py | 20 +++++++++++-- .../ns2/col/roles/foo/meta/argument_specs.yml | 10 +++++++ 19 files changed, 275 insertions(+), 12 deletions(-) create mode 100644 changelogs/fragments/156-indent-deprecation.yml diff --git a/changelogs/fragments/156-indent-deprecation.yml b/changelogs/fragments/156-indent-deprecation.yml new file mode 100644 index 00000000..68c9c2e3 --- /dev/null +++ b/changelogs/fragments/156-indent-deprecation.yml @@ -0,0 +1,3 @@ +bugfixes: + - "Indent module/plugin and role entrypoint deprecations correctly if 'Why' or 'Alternative' texts need more than one line (https://github.com/ansible-community/antsibull-docs/pull/156)." + - "Allow role entrypoint deprecations without having to specify the collection the role is removed from (https://github.com/ansible-community/antsibull-docs/pull/156)." diff --git a/src/antsibull_docs/data/docsite/plugin.rst.j2 b/src/antsibull_docs/data/docsite/plugin.rst.j2 index 3f3aaa45..7541d4fa 100644 --- a/src/antsibull_docs/data/docsite/plugin.rst.j2 +++ b/src/antsibull_docs/data/docsite/plugin.rst.j2 @@ -137,8 +137,8 @@ DEPRECATED {% if doc['deprecated']['removed_from_collection'] and doc['deprecated']['removed_from_collection'] != collection %} of @{ doc['deprecated']['removed_from_collection'] | rst_ify }@ {% endif %} -:Why: @{ doc['deprecated']['why'] | rst_ify }@ -:Alternative: @{ doc['deprecated']['alternative'] | rst_ify }@ +:Why: @{ doc['deprecated']['why'] | rst_ify | indent(6) }@ +:Alternative: @{ doc['deprecated']['alternative'] | rst_ify | indent(14) }@ {% endif %} {% if plugin_type == 'callback' %} diff --git a/src/antsibull_docs/data/docsite/role.rst.j2 b/src/antsibull_docs/data/docsite/role.rst.j2 index a214ed09..7313c393 100644 --- a/src/antsibull_docs/data/docsite/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/role.rst.j2 @@ -115,8 +115,8 @@ DEPRECATED {% else %} :Removed in: a future release {% endif %} -:Why: @{ ep_doc['deprecated']['why'] | rst_ify(role_entrypoint=entry_point) }@ -:Alternative: @{ ep_doc['deprecated']['alternative'] | rst_ify(role_entrypoint=entry_point) }@ +:Why: @{ ep_doc['deprecated']['why'] | rst_ify(role_entrypoint=entry_point) | indent(6) }@ +:Alternative: @{ ep_doc['deprecated']['alternative'] | rst_ify(role_entrypoint=entry_point) | indent(14) }@ {% endif %} Synopsis diff --git a/src/antsibull_docs/schemas/docs/role.py b/src/antsibull_docs/schemas/docs/role.py index 94fd14cb..fa9583a5 100644 --- a/src/antsibull_docs/schemas/docs/role.py +++ b/src/antsibull_docs/schemas/docs/role.py @@ -11,6 +11,7 @@ # pyre-ignore-all-errors[13] import typing as t +from collections.abc import Mapping import pydantic as p @@ -27,6 +28,8 @@ SeeAlsoRefSchema, ) +_SENTINEL = object() + class InnerRoleOptionsSchema(OptionsSchema): options: t.Dict[str, 'InnerRoleOptionsSchema'] = {} @@ -70,3 +73,20 @@ class RoleSchema(BaseModel): collection: str = COLLECTION_NAME_F entry_points: t.Dict[str, RoleEntrypointSchema] path: str + + @p.root_validator(pre=True) + # pylint:disable=no-self-argument + def add_entrypoint_deprecation_collection(cls, values): + entry_points = values.get("entry_points") + collection = values.get("collection") + if isinstance(entry_points, Mapping) and isinstance(collection, str): + for data in entry_points.values(): + if isinstance(data, Mapping): + deprecation = data.get("deprecated") + if isinstance(deprecation, Mapping): + removed_from_collection = deprecation.get( + "removed_from_collection", _SENTINEL + ) + if removed_from_collection is _SENTINEL: + deprecation["removed_from_collection"] = collection + return values diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json index e3c22086..8fe8f39a 100644 --- a/tests/functional/ansible-doc-cache-all.json +++ b/tests/functional/ansible-doc-cache-all.json @@ -5,6 +5,12 @@ "doc": { "author": "Nobody (!UNKNOWN)", "collection": "ns2.col", + "deprecated": { + "alternatives": "I don't know\nof any\nalternative.\n", + "removed_from_collection": "ns2.col", + "removed_in": "5.0.0", + "why": "Just some text.\nThis one has more than one line.\nAnd one more.\n" + }, "description": [ "This become plugin uses foo.", "This is a second paragraph." @@ -14,10 +20,10 @@ "options": { "bar": { "deprecated": { - "alternatives": "nothing", + "alternatives": "nothing\nrelevant\nI know of\n", "collection_name": "ns2.col", "version": "4.0.0", - "why": "Just some other text." + "why": "Just some other text.\nThis one has more than one line though.\nOne more.\n" }, "description": [ "Bar. B(BAR!)", @@ -1467,6 +1473,11 @@ "author": [ "Felix Fontein (@felixfontein)" ], + "deprecated": { + "alternatives": "I don't know\nof any\nalternative.\n", + "removed_in": "5.0.0", + "why": "Just some text.\nThis one has more than one line.\nAnd one more.\n" + }, "description": [ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." diff --git a/tests/functional/ansible-doc-cache-ns2.col.json b/tests/functional/ansible-doc-cache-ns2.col.json index 50c437fe..fc07e66d 100644 --- a/tests/functional/ansible-doc-cache-ns2.col.json +++ b/tests/functional/ansible-doc-cache-ns2.col.json @@ -5,6 +5,12 @@ "doc": { "author": "Nobody (!UNKNOWN)", "collection": "ns2.col", + "deprecated": { + "alternatives": "I don't know\nof any\nalternative.\n", + "removed_from_collection": "ns2.col", + "removed_in": "5.0.0", + "why": "Just some text.\nThis one has more than one line.\nAnd one more.\n" + }, "description": [ "This become plugin uses foo.", "This is a second paragraph." @@ -14,10 +20,10 @@ "options": { "bar": { "deprecated": { - "alternatives": "nothing", + "alternatives": "nothing\nrelevant\nI know of\n", "collection_name": "ns2.col", "version": "4.0.0", - "why": "Just some other text." + "why": "Just some other text.\nThis one has more than one line though.\nOne more.\n" }, "description": [ "Bar. B(BAR!)", @@ -1232,6 +1238,11 @@ "author": [ "Felix Fontein (@felixfontein)" ], + "deprecated": { + "alternatives": "I don't know\nof any\nalternative.\n", + "removed_in": "5.0.0", + "why": "Just some text.\nThis one has more than one line.\nAnd one more.\n" + }, "description": [ "This is the foo role.", "If you set O(foo_param_1) while O(foo_param_2=3), this might behave funny." diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_become.rst b/tests/functional/baseline-default/collections/ns2/col/foo_become.rst index 4229aae6..5bff2fc4 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_become.rst @@ -58,6 +58,17 @@ ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ .. Deprecated +DEPRECATED +---------- +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis -------- @@ -119,8 +130,14 @@ Parameters Removed in: version 4.0.0 Why: Just some other text. + This one has more than one line though. + One more. + Alternative: nothing + relevant + I know of + @@ -339,6 +356,15 @@ Parameters .. Status (Presently only deprecated) +Status +------ + +.. Deprecated note + +- This become will be removed in version 5.0.0. + *[deprecated]* +- For more information see `DEPRECATED`_. + .. Authors diff --git a/tests/functional/baseline-default/collections/ns2/col/foo_role.rst b/tests/functional/baseline-default/collections/ns2/col/foo_role.rst index 084a16f8..3ea9c9a0 100644 --- a/tests/functional/baseline-default/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-default/collections/ns2/col/foo_role.rst @@ -58,6 +58,17 @@ New in ns2.col 0.2.0 .. Deprecated +DEPRECATED +^^^^^^^^^^ +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis ^^^^^^^^ diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst index 4229aae6..5bff2fc4 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst @@ -58,6 +58,17 @@ ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ .. Deprecated +DEPRECATED +---------- +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis -------- @@ -119,8 +130,14 @@ Parameters Removed in: version 4.0.0 Why: Just some other text. + This one has more than one line though. + One more. + Alternative: nothing + relevant + I know of + @@ -339,6 +356,15 @@ Parameters .. Status (Presently only deprecated) +Status +------ + +.. Deprecated note + +- This become will be removed in version 5.0.0. + *[deprecated]* +- For more information see `DEPRECATED`_. + .. Authors diff --git a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst index 084a16f8..3ea9c9a0 100644 --- a/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst @@ -58,6 +58,17 @@ New in ns2.col 0.2.0 .. Deprecated +DEPRECATED +^^^^^^^^^^ +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis ^^^^^^^^ diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst index 4229aae6..5bff2fc4 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst @@ -58,6 +58,17 @@ ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ .. Deprecated +DEPRECATED +---------- +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis -------- @@ -119,8 +130,14 @@ Parameters Removed in: version 4.0.0 Why: Just some other text. + This one has more than one line though. + One more. + Alternative: nothing + relevant + I know of + @@ -339,6 +356,15 @@ Parameters .. Status (Presently only deprecated) +Status +------ + +.. Deprecated note + +- This become will be removed in version 5.0.0. + *[deprecated]* +- For more information see `DEPRECATED`_. + .. Authors diff --git a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst index 084a16f8..3ea9c9a0 100644 --- a/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst @@ -58,6 +58,17 @@ New in ns2.col 0.2.0 .. Deprecated +DEPRECATED +^^^^^^^^^^ +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis ^^^^^^^^ diff --git a/tests/functional/baseline-squash-hierarchy/foo_become.rst b/tests/functional/baseline-squash-hierarchy/foo_become.rst index 4229aae6..5bff2fc4 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_become.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_become.rst @@ -58,6 +58,17 @@ ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ .. Deprecated +DEPRECATED +---------- +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis -------- @@ -119,8 +130,14 @@ Parameters Removed in: version 4.0.0 Why: Just some other text. + This one has more than one line though. + One more. + Alternative: nothing + relevant + I know of + @@ -339,6 +356,15 @@ Parameters .. Status (Presently only deprecated) +Status +------ + +.. Deprecated note + +- This become will be removed in version 5.0.0. + *[deprecated]* +- For more information see `DEPRECATED`_. + .. Authors diff --git a/tests/functional/baseline-squash-hierarchy/foo_role.rst b/tests/functional/baseline-squash-hierarchy/foo_role.rst index 084a16f8..3ea9c9a0 100644 --- a/tests/functional/baseline-squash-hierarchy/foo_role.rst +++ b/tests/functional/baseline-squash-hierarchy/foo_role.rst @@ -58,6 +58,17 @@ New in ns2.col 0.2.0 .. Deprecated +DEPRECATED +^^^^^^^^^^ +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis ^^^^^^^^ diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst index becf20af..e48b35c2 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_become.rst @@ -58,6 +58,17 @@ ns2.col.foo become -- Use foo \ :ansopt:`ns2.col.foo#become:bar`\ .. Deprecated +DEPRECATED +---------- +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis -------- @@ -103,8 +114,14 @@ Parameters

added in ns2.col 1.2.0

Removed in: version 4.0.0

-

Why: Just some other text.

-

Alternative: nothing

+

Why: Just some other text. + This one has more than one line though. + One more. +

+

Alternative: nothing + relevant + I know of +

@@ -247,6 +264,15 @@ Parameters .. Status (Presently only deprecated) +Status +------ + +.. Deprecated note + +- This become will be removed in version 5.0.0. + *[deprecated]* +- For more information see `DEPRECATED`_. + .. Authors diff --git a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst index b715199c..86ffafb3 100644 --- a/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst +++ b/tests/functional/baseline-use-html-blobs/collections/ns2/col/foo_role.rst @@ -58,6 +58,17 @@ New in ns2.col 0.2.0 .. Deprecated +DEPRECATED +^^^^^^^^^^ +:Removed in: version 5.0.0 +:Why: Just some text. + This one has more than one line. + And one more. + +:Alternative: I don't know + of any + alternative. + Synopsis ^^^^^^^^ diff --git a/tests/functional/collections/ansible_collections/ns2/col/meta/runtime.yml b/tests/functional/collections/ansible_collections/ns2/col/meta/runtime.yml index 313fcac4..baa3eae2 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/meta/runtime.yml +++ b/tests/functional/collections/ansible_collections/ns2/col/meta/runtime.yml @@ -11,3 +11,10 @@ action_groups: - foo2 bar_group: - foo2 + +plugin_routing: + become: + foo: + deprecation: + removal_version: 5.0.0 + warning_text: It will be gone diff --git a/tests/functional/collections/ansible_collections/ns2/col/plugins/become/foo.py b/tests/functional/collections/ansible_collections/ns2/col/plugins/become/foo.py index b8140194..9cedf80e 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/plugins/become/foo.py +++ b/tests/functional/collections/ansible_collections/ns2/col/plugins/become/foo.py @@ -14,6 +14,16 @@ - This is a second paragraph. author: Nobody (!UNKNOWN) version_added: historical + deprecated: + removed_in: 5.0.0 + why: | + Just some text. + This one has more than one line. + And one more. + alternatives: | + I don't know + of any + alternative. options: become_user: description: User you 'become' to execute the task. @@ -72,9 +82,15 @@ type: str version_added: 1.2.0 deprecated: - why: Just some other text. + why: | + Just some other text. + This one has more than one line though. + One more. version: 4.0.0 - alternatives: nothing + alternatives: | + nothing + relevant + I know of """ from ansible.plugins.become import BecomeBase diff --git a/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml b/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml index dbc69ffd..52e641f7 100644 --- a/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml +++ b/tests/functional/collections/ansible_collections/ns2/col/roles/foo/meta/argument_specs.yml @@ -28,3 +28,13 @@ argument_specs: support: full seealso: - module: ns2.col.foo + deprecated: + removed_in: 5.0.0 + why: | + Just some text. + This one has more than one line. + And one more. + alternatives: | + I don't know + of any + alternative. From b6ab500588c9596b8d71b7aea4c526118e2c5821 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 9 Jun 2023 06:31:05 +0200 Subject: [PATCH 2/2] Ignore linting error. --- src/antsibull_docs/schemas/docs/role.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antsibull_docs/schemas/docs/role.py b/src/antsibull_docs/schemas/docs/role.py index fa9583a5..7c4c82e2 100644 --- a/src/antsibull_docs/schemas/docs/role.py +++ b/src/antsibull_docs/schemas/docs/role.py @@ -75,7 +75,7 @@ class RoleSchema(BaseModel): path: str @p.root_validator(pre=True) - # pylint:disable=no-self-argument + # pylint:disable=no-self-argument,no-self-use def add_entrypoint_deprecation_collection(cls, values): entry_points = values.get("entry_points") collection = values.get("collection")