From 642158fd381fa0b02a75a3e47665b43fc3ba6f51 Mon Sep 17 00:00:00 2001
From: Kefu Chai <kchai@redhat.com>
Date: Fri, 12 Feb 2021 16:03:11 +0800
Subject: [PATCH] doc: group commands by prefix

as there are lots commands, the toc in sidebar is clutterred with them,
so would be better to group them.

Signed-off-by: Kefu Chai <kchai@redhat.com>
---
 doc/_ext/ceph_commands.py | 47 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/doc/_ext/ceph_commands.py b/doc/_ext/ceph_commands.py
index e0f1090be35b7..d52949f17ff17 100644
--- a/doc/_ext/ceph_commands.py
+++ b/doc/_ext/ceph_commands.py
@@ -179,12 +179,19 @@ class Sig:
 
 
 TEMPLATE = '''
-.. This file is automatically generated. do not modify
+{% set punct_char = '-' %}
+{# add a header if we have multiple commands in this section #}
+{% if commands | length > 1 %}
+{{ section }}
+{{ section | length * '-' }}
+{# and demote the subsection #}
+{% set punct_char = '^' %}
+{% endif %}
 
 {% for command in commands %}
 
 {{ command.prefix }}
-{{ command.prefix | length * '^' }}
+{{ command.prefix | length * punct_char }}
 
 {{ command.help | wordwrap(70)}}
 
@@ -215,6 +222,36 @@ Required Permissions:
 '''
 
 
+def group_by_prefix(commands):
+    last_prefix = None
+    grouped = []
+    for cmd in commands:
+        prefix = cmd.prefix.split(' ', 1)[0]
+        if prefix == last_prefix:
+            grouped.append(cmd)
+        elif last_prefix is None:
+            last_prefix = prefix
+            grouped = [cmd]
+        else:
+            yield last_prefix, grouped
+            last_prefix = prefix
+            grouped = [cmd]
+    assert grouped
+    yield last_prefix, grouped
+
+
+def render_commands(commands):
+    rendered = io.StringIO()
+    for section, grouped in group_by_prefix(commands):
+        logger.debug('rendering commands: %s: %d', section, len(grouped))
+        for cmd in grouped:
+            logger.info('%s ==> %s', section, cmd.prefix)
+        rendered.write(Template(TEMPLATE).render(
+            section=section,
+            commands=grouped))
+    return rendered.getvalue().split('\n')
+
+
 class CephMgrCommands(Directive):
     """
     extracts commands from specified mgr modules
@@ -309,8 +346,7 @@ class CephMgrCommands(Directive):
         return command
 
     def _render_cmds(self, commands):
-        rendered = Template(TEMPLATE).render(commands=list(commands))
-        lines = rendered.split("\n")
+        lines = render_commands(commands)
         assert lines
         lineno = self.lineno - self.state_machine.input_offset - 1
         source = self.state_machine.input_lines.source(lineno)
@@ -413,8 +449,7 @@ class CephMonCommands(Directive):
         return command
 
     def _render_cmds(self, commands):
-        rendered = Template(TEMPLATE).render(commands=list(commands))
-        lines = rendered.split("\n")
+        lines = render_commands(commands)
         assert lines
         lineno = self.lineno - self.state_machine.input_offset - 1
         source = self.state_machine.input_lines.source(lineno)
-- 
2.39.5