From 081c60b9d3d9d37e915f11073ac4d047e7888f33 Mon Sep 17 00:00:00 2001
From: Matt Clay <matt@mystile.com>
Date: Mon, 31 Jul 2023 13:04:17 -0700
Subject: [PATCH] Include subcommands in generated man pages (#81378)

Sub commands of `ansible-galaxy role` and `ansible-galaxy collection` are now documented.
---
 changelogs/fragments/man-page-subcommands.yml |  2 ++
 packaging/pep517_backend/_templates/man.j2    | 32 +++++++++++++------
 2 files changed, 24 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/fragments/man-page-subcommands.yml

diff --git a/changelogs/fragments/man-page-subcommands.yml b/changelogs/fragments/man-page-subcommands.yml
new file mode 100644
index 00000000000..d76704185f4
--- /dev/null
+++ b/changelogs/fragments/man-page-subcommands.yml
@@ -0,0 +1,2 @@
+bugfixes:
+  - man page build - Sub commands of ``ansible-galaxy role`` and ``ansible-galaxy collection`` are now documented.
diff --git a/packaging/pep517_backend/_templates/man.j2 b/packaging/pep517_backend/_templates/man.j2
index 9a8cb1d7931..e159ba1a56c 100644
--- a/packaging/pep517_backend/_templates/man.j2
+++ b/packaging/pep517_backend/_templates/man.j2
@@ -1,3 +1,24 @@
+{% macro render_action(parent, action, action_docs) -%}
+**{{ parent + action }}**
+  {{ (action_docs['desc']|default(' ')) |replace('\n', ' ')}}
+
+{% if action_docs['options'] %}
+{% for option in action_docs['options']|sort(attribute='options') %}
+{% for switch in option['options'] if switch in action_docs['option_names'] %}  **{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
+
+        {{ (option['desc']) }}
+{% endfor %}
+{% endif %}
+
+{% set nested_actions = action_docs['actions'] %}
+{% if nested_actions %}
+{% for nested_action in nested_actions %}
+{{ render_action(parent + action + ' ', nested_action, nested_actions[nested_action]) }}
+{% endfor %}
+{% endif %}
+
+{%- endmacro %}
+
 {{ cli_name }}
 {{ '=' * ( cli_name|length|int ) }}
 
@@ -46,16 +67,7 @@ ARGUMENTS
 ACTIONS
 -------
 {% for action in actions %}
-**{{ action }}**
-  {{ (actions[action]['desc']|default(' ')) |replace('\n', ' ')}}
-
-{% if actions[action]['options'] %}
-{% for option in actions[action]['options']|sort(attribute='options') %}
-{% for switch in option['options'] if switch in actions[action]['option_names'] %}  **{{switch}}**{% if option['arg'] %} '{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
-
-        {{ (option['desc']) }}
-{% endfor %}
-{% endif %}
+{{ render_action('', action, actions[action]) }}
 {% endfor %}
 {% endif %}