From 1dbc32f69ab70d94aa9f4fbfcd2bf82b161f186f Mon Sep 17 00:00:00 2001
From: Kefu Chai <kchai@redhat.com>
Date: Fri, 12 Feb 2021 18:00:08 +0800
Subject: [PATCH] doc: define command properties using field list

the rendering is more compacted this way, and the parameters can be
aligned.

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

diff --git a/doc/_ext/ceph_commands.py b/doc/_ext/ceph_commands.py
index d52949f17ff..bafcd1ba084 100644
--- a/doc/_ext/ceph_commands.py
+++ b/doc/_ext/ceph_commands.py
@@ -179,7 +179,7 @@ class Sig:
 
 
 TEMPLATE = '''
-{% set punct_char = '-' %}
+{%- set punct_char = '-' -%}
 {# add a header if we have multiple commands in this section #}
 {% if commands | length > 1 %}
 {{ section }}
@@ -187,38 +187,28 @@ TEMPLATE = '''
 {# and demote the subsection #}
 {% set punct_char = '^' %}
 {% endif %}
-
 {% for command in commands %}
-
 {{ command.prefix }}
 {{ command.prefix | length * punct_char }}
 
-{{ command.help | wordwrap(70)}}
-
-Example command:
-
-.. code-block:: bash
-
-    {{ command.mk_bash_example() }}
-{% if command.params %}
-Parameters:
-
-{% for param in command.params %}* **{{param.name}}**: {{ param.help() | wordwrap(70) | indent(2) }}
-{% endfor %}{% endif %}
-Ceph Module:
+{{ command.help | wordwrap(70) }}
 
-* *{{ command.module }}*
+:Example command:
+    .. code-block:: bash
 
-Required Permissions:
+       {{ command.mk_bash_example() }}
 
-* *{{ command.perm }}*
-
-{% if command.flags %}Command Flags:
-
-* *{{ command.flags }}*
+{%- if command.params %}
+:Parameters:{% for param in command.params -%}
+{{" -" | indent(12, not loop.first) }} **{{param.name}}**: {{ param.help() }}
+{% endfor %}
+{% endif %}
+:Ceph Module: {{ command.module }}
+:Required Permissions: ``{{ command.perm }}``
+{%- if command.flags %}
+:Command Flags: ``{{ command.flags }}``
 {% endif %}
 {% endfor %}
-
 '''
 
 
@@ -244,8 +234,6 @@ 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))
-- 
2.39.5