From a07c986dbc893dd3e87be95a3a13841ae1279952 Mon Sep 17 00:00:00 2001
From: Hamish Willee <hamishwillee@gmail.com>
Date: Fri, 26 Jul 2024 07:46:11 +1000
Subject: [PATCH] Params generated as markdown table (#23443)

---
 src/lib/parameters/px4params/markdownout.py | 86 +++++++--------------
 1 file changed, 26 insertions(+), 60 deletions(-)

diff --git a/src/lib/parameters/px4params/markdownout.py b/src/lib/parameters/px4params/markdownout.py
index f83c504f80..34e6f9e386 100644
--- a/src/lib/parameters/px4params/markdownout.py
+++ b/src/lib/parameters/px4params/markdownout.py
@@ -17,38 +17,21 @@ If a listed parameter is missing from the Firmware see: [Finding/Updating Parame
 
 <!-- markdown generator: src/lib/parameters/px4params/markdownout.py -->
 
-<style>
-tr > * {
-    vertical-align : top;
-}
-td:nth-child(1),td:nth-child(2) {
-  text-align : left;
-  }
-table {
-  width: fit-content;
-}
-</style>
-
 """
                   )
 
         for group in groups:
-            result += '## %s\n\n' % group.GetName()
-            result += (
-"""<table>
- <colgroup><col style="width: 23%"><col style="width: 46%"><col style="width: 11%"><col style="width: 11%"><col style="width: 9%"></colgroup>
- <thead>
-   <tr><th>Name</th><th>Description</th><th>[Min, Max] (Incr.)</th><th>Default</th><th>Units</th></tr>
- </thead>
-<tbody>
-"""
-            )
+            result += f'## {group.GetName()}\n\n'
+
             for param in group.GetParams():
-                code = param.GetName()
-                name = param.GetFieldValue("short_desc") or ''
-                name = html.escape(name)
+                name = param.GetName()
+                short_desc = param.GetFieldValue("short_desc") or ''
+                if short_desc:
+                    if not short_desc.strip().endswith('.'):
+                        short_desc += "."
+                #short_desc = html.escape(short_desc)
                 long_desc = param.GetFieldValue("long_desc") or ''
-                long_desc = html.escape(long_desc)
+                #long_desc = html.escape(long_desc)
                 min_val = param.GetFieldValue("min") or ''
                 max_val = param.GetFieldValue("max") or ''
                 increment = param.GetFieldValue("increment") or ''
@@ -62,60 +45,43 @@ table {
                 #field_codes = param.GetFieldCodes() ## Disabled as not needed for display.
                 #boolean = param.GetFieldValue("boolean") # or '' # Disabled - does not appear useful.
 
-
                 # Format values for display.
-                # Display min/max/increment value based on what values are defined.
-                max_min_combined = ''
-                if min_val or max_val:
-                    if not min_val:
-                        min_val='?'
-                    if not max_val:
-                        max_val='?'
-                    max_min_combined+=f"[{min_val}, {max_val}] "
-                if increment:
-                    max_min_combined+='(%s)' % increment
-
-                if long_desc != '':
-                    long_desc = f"<p><strong>Comment:</strong> {long_desc}</p>"
-
-                if name == code:
-                    name = ""
-                code=f"<strong id=\"{code}\">{code}</strong>"
-
-                if reboot_required:
-                    reboot_required='<p><b>Reboot required:</b> %s</p>\n' % reboot_required
-
                 enum_codes=param.GetEnumCodes() or '' # Gets numerical values for parameter.
                 enum_output=''
                 # Format codes and their descriptions for display.
                 if enum_codes:
-                    enum_output+='<strong>Values:</strong><ul>'
+                    enum_output+='**Values:**\n\n'
                     enum_codes=sorted(enum_codes,key=float)
                     for item in enum_codes:
-                        enum_output+=f"\n<li><strong>{item}:</strong> {html.escape(param.GetEnumValue(item))}</li>"
-                    enum_output+='\n</ul>'
-
+                        enum_output+=f"- `{item}`: {param.GetEnumValue(item)}\n"
+                    enum_output+='\n\n'
 
                 bitmask_list=param.GetBitmaskList() #Gets bitmask values for parameter
                 bitmask_output=''
                 #Format bitmask values
                 if bitmask_list:
-                    bitmask_output+='<strong>Bitmask:</strong><ul>'
+                    bitmask_output+='**Bitmask:**\n\n'
                     for bit in bitmask_list:
                         bit_text = param.GetBitmaskBit(bit)
-                        bit_text = html.escape(bit_text)
-                        bitmask_output+=f"  <li><strong>{bit}:</strong> {bit_text}</li>\n"
-                    bitmask_output+='</ul>\n'
+                        bitmask_output+=f"- `{bit}`: {bit_text}\n"
+                    bitmask_output+='\n\n'
 
                 if is_boolean and def_val=='1':
                     def_val='Enabled (1)'
                 if is_boolean and def_val=='0':
                     def_val='Disabled (0)'
 
-                result += f"<tr>\n <td>{code} ({type})</td>\n <td>{name} {long_desc} {enum_output} {bitmask_output} {reboot_required}</td>\n <td>{max_min_combined}</td>\n <td>{def_val}</td>\n <td>{unit}</td>\n</tr>\n"
-
-            #Close the table.
-            result += '</tbody></table>\n\n'
+                result += f'### {name} (`{type}`)' + ' {#' + name + '}\n\n'
+                if short_desc:
+                    result += f'{short_desc}\n\n'
+                if long_desc:
+                    result += f'{long_desc}\n\n'
+                if enum_codes:
+                    result += enum_output
+                if bitmask_list:
+                    result += bitmask_output
+                # Format the ranges as a table.
+                result += f"Reboot | minValue | maxValue | increment | default | unit\n--- | --- | --- | --- | --- | ---\n{reboot_required} | {min_val} | {max_val} | {increment} | {def_val} | {unit} \n\n"
 
         self.output = result