diff --git a/changelogs/fragments/329-keywords.yml b/changelogs/fragments/329-keywords.yml new file mode 100644 index 00000000..d61bddec --- /dev/null +++ b/changelogs/fragments/329-keywords.yml @@ -0,0 +1,2 @@ +minor_changes: + - Support new ``keyword`` field in plugin documentations (https://github.com/ansible-community/antsibull/pull/329). diff --git a/src/antsibull/data/docsite/macros/parameters.rst.j2 b/src/antsibull/data/docsite/macros/parameters.rst.j2 index 98d306a0..f3457ffa 100644 --- a/src/antsibull/data/docsite/macros/parameters.rst.j2 +++ b/src/antsibull/data/docsite/macros/parameters.rst.j2 @@ -145,6 +145,14 @@ {% endif %} @{ deprecates_rst(myvar['deprecated'], collection, 8) }@ {% endfor %} +{% for kw in value['keyword'] %} + - Keyword: @{ kw['name'] | rst_escape }@ +{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %} + + :ansible-option-versionadded:`added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | rst_ify }@` +{% endif %} +@{ deprecates_rst(kw['deprecated'], collection, 8) }@ +{% endfor %} {% for mycli in value['cli'] %} - CLI argument: @{ mycli['option'] | rst_escape }@ {% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection']) %} @@ -279,6 +287,15 @@ @{ deprecates_html(myvar['deprecated'], collection) }@ {% endfor %} +{% for kw in value['keyword'] %} +
  • +

    Keyword: @{ kw['name'] | escape }@

    +{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %} +

    added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | html_ify }@

    +{% endif %} +@{ deprecates_html(kw['deprecated'], collection) }@ +
    • +{% endfor %} {% for mycli in value['cli'] %}

  • CLI argument: @{ mycli['option'] | escape }@

    diff --git a/src/antsibull/schemas/docs/plugin.py b/src/antsibull/schemas/docs/plugin.py index 436cc0af..1c3b895d 100644 --- a/src/antsibull/schemas/docs/plugin.py +++ b/src/antsibull/schemas/docs/plugin.py @@ -63,6 +63,13 @@ class OptionVarsSchema(BaseModel): version_added_collection: str = COLLECTION_NAME_F +class OptionKeywordSchema(BaseModel): + name: str + deprecated: DeprecationSchema = p.Field({}) + version_added: str = 'historical' + version_added_collection: str = COLLECTION_NAME_F + + class ReturnSchema(BaseModel): """Schema of plugin return data docs.""" @@ -145,6 +152,7 @@ class PluginOptionsSchema(OptionsSchema): ini: t.List[OptionIniSchema] = [] suboptions: t.Dict[str, 'PluginOptionsSchema'] = {} vars: t.List[OptionVarsSchema] = [] + keyword: t.List[OptionKeywordSchema] = [] deprecated: DeprecationSchema = p.Field({}) diff --git a/tests/functional/schema/good_data/one_become_results.json b/tests/functional/schema/good_data/one_become_results.json index f17af050..dbe0bbb4 100644 --- a/tests/functional/schema/good_data/one_become_results.json +++ b/tests/functional/schema/good_data/one_become_results.json @@ -53,6 +53,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/one_cache_results.json b/tests/functional/schema/good_data/one_cache_results.json index 25ee2160..805c3bd0 100644 --- a/tests/functional/schema/good_data/one_cache_results.json +++ b/tests/functional/schema/good_data/one_cache_results.json @@ -44,6 +44,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -78,6 +79,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -112,6 +114,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": true, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/one_cliconf_results.json b/tests/functional/schema/good_data/one_cliconf_results.json index 8b58c480..94be039e 100644 --- a/tests/functional/schema/good_data/one_cliconf_results.json +++ b/tests/functional/schema/good_data/one_cliconf_results.json @@ -36,6 +36,7 @@ } ], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", diff --git a/tests/functional/schema/good_data/one_connection_results.json b/tests/functional/schema/good_data/one_connection_results.json index 036599e1..511ce50f 100644 --- a/tests/functional/schema/good_data/one_connection_results.json +++ b/tests/functional/schema/good_data/one_connection_results.json @@ -45,6 +45,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -86,6 +87,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -112,6 +114,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -138,6 +141,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -164,6 +168,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -217,6 +222,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -258,6 +264,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -300,6 +307,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -342,6 +350,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -384,6 +393,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -410,6 +420,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -436,6 +447,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -462,6 +474,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", diff --git a/tests/functional/schema/good_data/one_httpapi_results.json b/tests/functional/schema/good_data/one_httpapi_results.json index f8b14413..59bd3979 100644 --- a/tests/functional/schema/good_data/one_httpapi_results.json +++ b/tests/functional/schema/good_data/one_httpapi_results.json @@ -29,6 +29,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/one_inventory_results.json b/tests/functional/schema/good_data/one_inventory_results.json index e129816d..85cb5382 100644 --- a/tests/functional/schema/good_data/one_inventory_results.json +++ b/tests/functional/schema/good_data/one_inventory_results.json @@ -53,6 +53,7 @@ } ], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -87,6 +88,7 @@ } ], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -127,6 +129,7 @@ } ], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -165,6 +168,7 @@ } ], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -199,6 +203,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -246,6 +251,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -293,6 +299,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -340,6 +347,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -387,6 +395,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -406,6 +415,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "dict", @@ -426,6 +436,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "dict", @@ -445,6 +456,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "dict", @@ -466,6 +478,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "list", @@ -485,6 +498,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -505,6 +519,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -524,6 +539,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "list", @@ -545,6 +561,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": true, "suboptions": {}, "type": "str", @@ -565,6 +582,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "list", @@ -585,6 +603,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -605,6 +624,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -626,6 +646,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", diff --git a/tests/functional/schema/good_data/one_lookup_results.json b/tests/functional/schema/good_data/one_lookup_results.json index 865a4a5f..3430a812 100644 --- a/tests/functional/schema/good_data/one_lookup_results.json +++ b/tests/functional/schema/good_data/one_lookup_results.json @@ -28,6 +28,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": true, "suboptions": {}, "type": "list", @@ -62,6 +63,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -81,6 +83,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -116,6 +119,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -135,6 +139,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -155,6 +160,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -174,6 +180,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -194,6 +201,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -213,6 +221,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -247,6 +256,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/one_netconf_results.json b/tests/functional/schema/good_data/one_netconf_results.json index 9455c95d..3453b206 100644 --- a/tests/functional/schema/good_data/one_netconf_results.json +++ b/tests/functional/schema/good_data/one_netconf_results.json @@ -29,6 +29,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/one_shell_results.json b/tests/functional/schema/good_data/one_shell_results.json index cfe69c6d..a1db21ce 100644 --- a/tests/functional/schema/good_data/one_shell_results.json +++ b/tests/functional/schema/good_data/one_shell_results.json @@ -45,6 +45,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "list", @@ -86,6 +87,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -112,6 +114,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "dict", @@ -152,6 +155,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -196,6 +200,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "list", diff --git a/tests/functional/schema/good_data/one_vars_results.json b/tests/functional/schema/good_data/one_vars_results.json index 2b3f065a..2b2b430e 100644 --- a/tests/functional/schema/good_data/one_vars_results.json +++ b/tests/functional/schema/good_data/one_vars_results.json @@ -51,6 +51,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "list", @@ -93,6 +94,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", diff --git a/tests/functional/schema/good_data/ssh_connection.json b/tests/functional/schema/good_data/ssh_connection.json index 87b149aa..d1462a1e 100644 --- a/tests/functional/schema/good_data/ssh_connection.json +++ b/tests/functional/schema/good_data/ssh_connection.json @@ -192,6 +192,11 @@ { "name": "ansible_ssh_port" } + ], + "keyword": [ + { + "name": "port" + } ] }, "private_key_file": { @@ -252,6 +257,11 @@ { "name": "ansible_ssh_user" } + ], + "keyword": [ + { + "name": "remote_user" + } ] }, "retries": { diff --git a/tests/functional/schema/good_data/ssh_connection_results.json b/tests/functional/schema/good_data/ssh_connection_results.json index 00c133bf..6090120d 100644 --- a/tests/functional/schema/good_data/ssh_connection_results.json +++ b/tests/functional/schema/good_data/ssh_connection_results.json @@ -50,6 +50,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -92,6 +93,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -118,6 +120,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -196,6 +199,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -228,6 +232,7 @@ "elements": "str", "env": [], "ini": [], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -296,6 +301,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -343,6 +349,14 @@ "version_added_collection": "" } ], + "keyword": [ + { + "deprecated": {}, + "name": "port", + "version_added": "historical", + "version_added_collection": "" + } + ], "required": false, "suboptions": {}, "type": "int", @@ -398,6 +412,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -454,6 +469,14 @@ "version_added_collection": "" } ], + "keyword": [ + { + "deprecated": {}, + "name": "remote_user", + "version_added": "historical", + "version_added_collection": "" + } + ], "required": false, "suboptions": {}, "type": "str", @@ -508,6 +531,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -549,6 +573,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -598,6 +623,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -641,6 +667,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -682,6 +709,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool", @@ -723,6 +751,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -772,6 +801,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -821,6 +851,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -870,6 +901,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -912,6 +944,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -961,6 +994,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -1009,6 +1043,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -1043,6 +1078,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "str", @@ -1106,6 +1142,7 @@ "version_added_collection": "ansible.builtin" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "int", @@ -1147,6 +1184,7 @@ "version_added_collection": "" } ], + "keyword": [], "required": false, "suboptions": {}, "type": "bool",