Repository: ansible-community/antsibull-docs (language: python)

Issue:
Fix deprecations for plugins and role entrypoints
- Fix indent of 'Why' and 'Alternative' texts for deprecations. If these texts happen to be multiple lines long, the other lines must be indented.
- Allow role entrypoint deprecations without explicitly specifying `removed_from_collection` (which is the collection the role is part of anyway).



Discussion / hints:

Fix patch:
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..7c4c82e2 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,no-self-use
+    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


Test patch:
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
       </p>
       <p><span class="ansible-option-versionadded">added in ns2.col 1.2.0</span></p>
   <p>Removed in: version 4.0.0</p>
-  <p>Why: Just some other text.</p>
-  <p>Alternative: nothing</p>
+  <p>Why: Just some other text.
+  This one has more than one line though.
+  One more.
+  </p>
+  <p>Alternative: nothing
+  relevant
+  I know of
+  </p>
 
     </div></td>
     <td><div class="ansible-option-cell">
@@ -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.