From 034a8115ce4aa13d6305482330b7a595cbefed16 Mon Sep 17 00:00:00 2001
From: Chad Smith <chad.smith@canonical.com>
Date: Thu, 25 Jul 2024 16:01:15 -0600
Subject: [PATCH] fix(doc): doc of nested objects under JSON schema items.oneOf
 (#5562)

Document any keys of objects in a list which allows for objects as one
of the alternative types allowed as a list item.

Also, when documenting properties, ensure we skip documentation of
either 'properties' or 'patternProperties' if those properties are
declared in the hidden key.

Fixes GH-5514
---
 doc/rtd/conf.py | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index cfa1f63df63d..8efe5e53a11e 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -256,23 +256,28 @@ def render_property_template(prop_name, prop_cfg, prefix=""):
 
 def render_nested_properties(prop_cfg, defs, prefix):
     prop_str = ""
+    prop_types = set(["properties", "patternProperties"])
     flatten_schema_refs(prop_cfg, defs)
     if "items" in prop_cfg:
         prop_str += render_nested_properties(prop_cfg["items"], defs, prefix)
-    if not set(["properties", "patternProperties"]).intersection(prop_cfg):
-        return prop_str
-    for prop_name, nested_cfg in prop_cfg.get("properties", {}).items():
-        flatten_schema_all_of(nested_cfg)
-        flatten_schema_refs(nested_cfg, defs)
-        prop_str += render_property_template(prop_name, nested_cfg, prefix)
-        prop_str += render_nested_properties(nested_cfg, defs, prefix + "  ")
-    for prop_name, nested_cfg in prop_cfg.get("patternProperties", {}).items():
-        flatten_schema_all_of(nested_cfg)
-        flatten_schema_refs(nested_cfg, defs)
-        if nested_cfg.get("label"):
-            prop_name = nested_cfg.get("label")
-        prop_str += render_property_template(prop_name, nested_cfg, prefix)
-        prop_str += render_nested_properties(nested_cfg, defs, prefix + "  ")
+        for alt_schema in prop_cfg["items"].get("oneOf", []):
+            if prop_types.intersection(alt_schema):
+                prop_str += render_nested_properties(alt_schema, defs, prefix)
+
+    for hidden_key in prop_cfg.get("hidden", []):
+        prop_cfg.pop(hidden_key, None)
+
+    # Render visible property types
+    for prop_type in prop_types.intersection(prop_cfg):
+        for prop_name, nested_cfg in prop_cfg.get(prop_type, {}).items():
+            flatten_schema_all_of(nested_cfg)
+            flatten_schema_refs(nested_cfg, defs)
+            if nested_cfg.get("label"):
+                prop_name = nested_cfg.get("label")
+            prop_str += render_property_template(prop_name, nested_cfg, prefix)
+            prop_str += render_nested_properties(
+                nested_cfg, defs, prefix + "  "
+            )
     return prop_str