Add support for 'keyword' (#329)

* Allow 'keyword' in schema. * Include 'keyword' in output. * Add changelog fragment.
ansible-community · Jan 21, 2022 · 8789427 · 8789427
1 parent 36fc1f7
commit 8789427
Show file tree

Hide file tree

Showing 15 changed files with 133 additions and 0 deletions.
diff --git a/changelogs/fragments/329-keywords.yml 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
@@ -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) }@
       </li>
 {%     endfor %}
+{%     for kw in value['keyword'] %}
+      <li>
+        <p>Keyword: @{ kw['name'] | escape }@</p>
+{%       if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %}
+        <p><span class="ansible-option-versionadded">added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | html_ify }@</span></p>
+{%       endif %}
+@{       deprecates_html(kw['deprecated'], collection) }@
+      </li>
+{%     endfor %}
 {%     for mycli in value['cli'] %}
       <li>
         <p>CLI argument: @{ mycli['option'] | escape }@</p>

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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",
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		minor_changes:
		- Support new ``keyword`` field in plugin documentations (https://github.com/ansible-community/antsibull/pull/329).