fix keyword doc generation

  * use aliases when they exist
  * fix hardcoded loop attributes handling

(cherry picked from commit 19fee0ef41b9632d4fdf2e48a9bbcd69a651e603)

2 files changed, 11 insertions, 4 deletions

diff --git a/changelogs/fragments/keyword_docgen.yml b/changelogs/fragments/keyword_docgen.yml
new file mode 100644
index 0000000000..e8c28f42ea
--- /dev/null
+++ b/changelogs/fragments/keyword_docgen.yml
@@ -0,0 +1,2 @@
+- bufgixes:
+    - Allow aliases and update corner cases for hidden fields https://github.com/ansible/ansible/pull/39506
diff --git a/docs/bin/dump_keywords.py b/docs/bin/dump_keywords.py
index 455fc12086..3b1a3eaf56 100755
--- a/docs/bin/dump_keywords.py
+++ b/docs/bin/dump_keywords.py
@@ -48,19 +48,24 @@ for aclass in class_list:
         if a in docs:
             oblist[name][a] = docs[a]
         else:
-            oblist[name][a] = ' UNDOCUMENTED!! '
+            # check if there is an alias, otherwise undocumented
+            alias = getattr(getattr(aobj, '_%s' % a), 'alias', None)
+            if alias and alias in docs:
+                oblist[name][alias] = docs[alias]
+                del oblist[name][a]
+            else:
+                oblist[name][a] = ' UNDOCUMENTED!! '
 
     # loop is really with_ for users
     if name == 'Task':
-        oblist[name]['with_<lookup_plugin>'] = 'DEPRECATED: use ``loop`` instead, ``with_`` used to be how loops were defined, '
-        'it can use any available lookup plugin to generate the item list'
+        oblist[name]['with_<lookup_plugin>'] = 'The same as ``loop`` but magically adds the output of any lookup plugin to generate the item list.'
 
     # local_action is implicit with action
     if 'action' in oblist[name]:
         oblist[name]['local_action'] = 'Same as action but also implies ``delegate_to: localhost``'
 
     # remove unusable (used to be private?)
-    for nouse in ('loop_args'):
+    for nouse in ('loop_args', 'loop_with'):
         if nouse in oblist[name]:
             del oblist[name][nouse]