From 47c8cfd26c77278c86cce4ba3670bfb04a7b2d74 Mon Sep 17 00:00:00 2001
From: Renan Rodrigo <renanrodrigo@canonical.com>
Date: Thu, 29 Aug 2024 01:24:51 -0300
Subject: [PATCH] docs: automatically generate the command entries for the rst
 docs

Make the clidocgen script generate a commands.txt file to be used
in the docs/references folder in the docs branch.

Signed-off-by: Renan Rodrigo <renanrodrigo@canonical.com>
---
 tools/clidocgen.py | 66 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/tools/clidocgen.py b/tools/clidocgen.py
index 47165d0f94..5980450b24 100755
--- a/tools/clidocgen.py
+++ b/tools/clidocgen.py
@@ -10,7 +10,40 @@
 from uaclient.cli import COMMANDS, get_parser
 from uaclient.cli.commands import ProCommand
 
-VALID_TARGETS = ["manpage"]
+VALID_TARGETS = ["manpage", "rst"]
+
+GENERATED_DOC_HEADER = """\
+..
+   THIS DOCUMENTATION WAS AUTOMATICALLY GENERATED
+   Do not edit this document directly. Instead, edit the commands in the cli
+   source code, which can be found on the main branch of the git repo at
+   https://github.com/canonical/ubuntu-pro-client. The cli source code is
+   nested in the uaclient/cli folder. Description for the commands is found
+   in the uaclient/messages folder.
+
+Available commands
+==================
+
+The currently available commands are:
+
+{commands_list}
+
+"""
+COMMAND_LINK_TEMPLATE = "- `{command_entry}`_\n"
+
+RST_TEMPLATE = """\
+{command}
+{section_mark}
+
+**Usage:**
+
+``{usage_line}``
+
+**Description:**
+
+{description}
+
+"""
 
 MANPAGE_TEMPLATE = """\
 .TP
@@ -20,6 +53,17 @@
 """
 
 
+def _build_rst_entry(command: ProCommand, section_mark: str = "="):
+    return RST_TEMPLATE.format(
+        command=command.parser.prog,
+        section_mark=section_mark * len(command.parser.prog),
+        usage_line=" ".join(
+            command.parser.format_usage()[len("usage: ") :].split()
+        ),
+        description=command.description,
+    )
+
+
 def _build_manpage_entry(command: ProCommand, indent: str = "") -> str:
     # the usage line looks like
     # usage: <prog> <options>
@@ -36,6 +80,23 @@ def _build_manpage_entry(command: ProCommand, indent: str = "") -> str:
     )
 
 
+def _generate_rst_section():
+    command_list = ""
+    for command in COMMANDS:
+        command_list += COMMAND_LINK_TEMPLATE.format(
+            command_entry=command.parser.prog
+        )
+
+    content = GENERATED_DOC_HEADER.format(commands_list=command_list)
+    for command in COMMANDS:
+        content += _build_rst_entry(command)
+        for subcommand in command.subcommands:
+            content += _build_rst_entry(subcommand, section_mark="-")
+
+    with open("./commands.txt", "w") as f:
+        f.write(content)
+
+
 def _generate_manpage_section():
     result = ""
     for command in COMMANDS:
@@ -57,5 +118,8 @@ def _generate_manpage_section():
         if sys.argv[1] == "manpage":
             _generate_manpage_section()
             sys.exit()
+        if sys.argv[1] == "rst":
+            _generate_rst_section()
+            sys.exit()
 
     raise ValueError("call the script with one of: " + " ".join(VALID_TARGETS))