Improve documentation appearance (#15231)

truenas · Dec 18, 2024 · 7244b98 · 7244b98
1 parent 246c8e6
commit 7244b98
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 1 deletion.
diff --git a/src/middlewared_docs/docs/_static/style.css b/src/middlewared_docs/docs/_static/style.css
@@ -8,3 +8,16 @@ ul.search li { background: none; }
 #json-schema h4 { display: none; }
 #json-schema .breadcrumbs { display: none; }
 #json-schema .no-additional { display: none; }
+#json-schema .json-default-value {
+    font-size: 75%;
+    padding: .25em .4em;
+    border: 2px solid #28a745;
+    border-radius: .25rem;
+    font-weight: 700;
+}
+#json-schema .json-default-value .value {
+    font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+    font-weight: 400;
+    margin-top: .25em;
+    white-space: pre;
+}
diff --git a/src/middlewared_docs/generate_docs.py b/src/middlewared_docs/generate_docs.py
@@ -106,9 +106,12 @@ def _generate_method_schemas_html(self, method: APIDumpMethod):
 
             soup = BeautifulSoup(html)
 
+            # Elements like `Each item of this array must be:`
             for h4 in soup.find_all("h4"):
                 if h4.text.endswith(":"):
-                    h4["style"] = "display: block;"
+                    h5 = soup.new_tag("h5")
+                    h5.string = h4.text
+                    h4.replace_with(h5)
 
             for h5 in soup.find("div", {"id": "Call_parameters"}).find().find_all("h5", recursive=False):
                 if m := re.match("Item at ([0-9]+) must be:", h5.text):
@@ -121,6 +124,22 @@ def _generate_method_schemas_html(self, method: APIDumpMethod):
                     name = next_sibling.find("h4").text
                     h5.string = f"Parameter {number}: {name}"
 
+            # Multi-line default values (usually, non-trivial JSON arrays/objects)
+            for default_value in soup.find_all("span", class_="default-value"):
+                value = default_value.text.split(": ", 1)[1]
+                if len(value) > 40 and value.startswith(("[", "{")):
+                    try:
+                        value_decoded = json.loads(value)
+                    except ValueError:
+                        continue
+
+                    new_default_value_value = soup.new_tag("div", **{"class": "value"})
+                    new_default_value_value.string = json.dumps(value_decoded, indent=2)
+                    new_default_value = soup.new_tag("div", **{"class": "json-default-value"})
+                    new_default_value.string = "Default:"
+                    new_default_value.insert(1, new_default_value_value)
+                    default_value.replace_with(new_default_value)
+
             return soup.find("body").decode_contents()
         finally:
             os.unlink(json_path)