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

[PR #156/2d3c65e2 backport][stable-1] Fix deprecations for plugins and role entrypoints #158

Merged
merged 2 commits into from
Jun 9, 2023
Merged

[PR #156/2d3c65e2 backport][stable-1] Fix deprecations for plugins and role entrypoints #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f585f6d
Fix deprecations for plugins and role entrypoints (#156)
felixfontein Jun 9, 2023
b6ab500
Ignore linting error.
felixfontein Jun 9, 2023
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
3 changes: 3 additions & 0 deletions changelogs/fragments/156-indent-deprecation.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)."
4 changes: 2 additions & 2 deletions src/antsibull_docs/data/docsite/plugin.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' %}
Expand Down
4 changes: 2 additions & 2 deletions src/antsibull_docs/data/docsite/role.rst.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions src/antsibull_docs/schemas/docs/role.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
# pyre-ignore-all-errors[13]

import typing as t
from collections.abc import Mapping

import pydantic as p

Expand All @@ -27,6 +28,8 @@
SeeAlsoRefSchema,
)

_SENTINEL = object()


class InnerRoleOptionsSchema(OptionsSchema):
options: t.Dict[str, 'InnerRoleOptionsSchema'] = {}
Expand Down Expand Up @@ -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
15 changes: 13 additions & 2 deletions tests/functional/ansible-doc-cache-all.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand All @@ -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!)",
Expand Down Expand Up @@ -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."
Expand Down
15 changes: 13 additions & 2 deletions tests/functional/ansible-doc-cache-ns2.col.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand All @@ -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!)",
Expand Down Expand Up @@ -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."
Expand Down
26 changes: 26 additions & 0 deletions tests/functional/baseline-default/collections/ns2/col/foo_become.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down Expand Up @@ -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




Expand Down Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions tests/functional/baseline-default/collections/ns2/col/foo_role.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^
Expand Down
26 changes: 26 additions & 0 deletions tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_become.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down Expand Up @@ -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




Expand Down Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions tests/functional/baseline-no-breadcrumbs/collections/ns2/col/foo_role.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^
Expand Down
26 changes: 26 additions & 0 deletions tests/functional/baseline-no-indexes/collections/ns2/col/foo_become.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down Expand Up @@ -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




Expand Down Expand Up @@ -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

Expand Down
11 changes: 11 additions & 0 deletions tests/functional/baseline-no-indexes/collections/ns2/col/foo_role.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^
Expand Down
26 changes: 26 additions & 0 deletions tests/functional/baseline-squash-hierarchy/foo_become.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down Expand Up @@ -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




Expand Down Expand Up @@ -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

Expand Down
Loading