Recursive rendering of children with their own page

Author: jorgepiloto

autoapi/mappers/base.py

@@ -327,6 +327,50 @@ def create_class(self, data, options=None, **kwargs):
         """
         raise NotImplementedError
 
+    def output_child_rst(self, obj, obj_parent, detail_dir, source_suffix):
+
+        if not obj.display:
+            return
+
+        # Skip nested cases like functions in functions or clases in clases
+        if obj.type == obj_parent.type:
+            return
+
+        obj_child_page_level = _OWN_PAGE_LEVELS.index(obj.type)
+        desired_page_level = _OWN_PAGE_LEVELS.index(self.app.config.autoapi_own_page_level)
+        is_own_page = obj_child_page_level <= desired_page_level
+        if not is_own_page:
+            return
+
+        obj_child_rst = obj.render(
+            is_own_page=is_own_page,
+        )
+        if not obj_child_rst:
+            return
+
+        function_page_level = _OWN_PAGE_LEVELS.index("function")
+        is_level_beyond_function = function_page_level < desired_page_level
+        if obj.type in ["exception", "class"]:
+            if not is_level_beyond_function:
+                outfile = f"{obj.short_name}{source_suffix}"
+                path = os.path.join(detail_dir, outfile)
+            else:
+                outdir = os.path.join(detail_dir, obj.short_name)
+                ensuredir(outdir)
+                path = os.path.join(outdir, f"index{source_suffix}")
+        else:
+            is_parent_in_detail_dir = detail_dir.endswith(obj_parent.short_name)
+            outdir = detail_dir if is_parent_in_detail_dir else os.path.join(detail_dir, obj_parent.short_name)
+            ensuredir(outdir)
+            path = os.path.join(outdir, f"{obj.short_name}{source_suffix}")
+
+        with open(path, "wb+") as obj_child_detail_file:
+            obj_child_detail_file.write(obj_child_rst.encode("utf-8"))
+
+        for obj_child in obj.children:
+            child_detail_dir = os.path.join(detail_dir, obj.name)
+            self.output_child_rst(obj_child, obj, child_detail_dir, source_suffix)
+
     def output_rst(self, root, source_suffix):
         for _, obj in status_iterator(
             self.objects_to_render.items(),
@@ -347,6 +391,9 @@ def output_rst(self, root, source_suffix):
             path = os.path.join(detail_dir, f"index{source_suffix}")
             with open(path, "wb+") as detail_file:
                 detail_file.write(rst.encode("utf-8"))
+            
+            for child in obj.children:
+                self.output_child_rst(child, obj, detail_dir, source_suffix)
 
         if self.app.config.autoapi_add_toctree_entry:
             self._output_top_rst(root)

autoapi/templates/python/class.rst

@@ -37,30 +37,69 @@
    {% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
    {% endif %}
    {% for klass in visible_classes %}
-   {{ klass.render()|indent(3) }}
+   {{ klass.render(own_page_types=[])|indent(3) }}
    {% endfor %}
    {% if "inherited-members" in autoapi_options %}
    {% set visible_properties = obj.properties|selectattr("display")|list %}
    {% else %}
    {% set visible_properties = obj.properties|rejectattr("inherited")|selectattr("display")|list %}
    {% endif %}
+   {% if "property" in own_page_types and visible_properties %}
+
+   Properties
+   ----------
+
+   .. toctree::
+      :hidden:
+
+      {% for property in visible_properties %}
+      {{ property.name }}
+      {% endfor %}
+   {% else %}
    {% for property in visible_properties %}
    {{ property.render()|indent(3) }}
    {% endfor %}
+   {% endif %}
    {% if "inherited-members" in autoapi_options %}
    {% set visible_attributes = obj.attributes|selectattr("display")|list %}
    {% else %}
    {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
    {% endif %}
+   {% if "attribute" in own_page_types and visible_attributes %}
+
+   Attributes
+   ----------
+
+   .. toctree::
+      :hidden:
+
+      {% for attribute in visible_attributes %}
+      {{ attribute.name }}
+      {% endfor %}
+   {% else %}
    {% for attribute in visible_attributes %}
    {{ attribute.render()|indent(3) }}
    {% endfor %}
+   {% endif %}
    {% if "inherited-members" in autoapi_options %}
    {% set visible_methods = obj.methods|selectattr("display")|list %}
    {% else %}
    {% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
    {% endif %}
+   {% if "method" in own_page_types and visible_methods %}
+
+   Methods
+   -------
+
+   .. toctree::
+      :hidden:
+
+      {% for method in visible_methods %}
+      {{ method.name }}
+      {% endfor %}
+   {% else %}
    {% for method in visible_methods %}
    {{ method.render()|indent(3) }}
    {% endfor %}
+   {% endif %}
 {% endif %}

autoapi/templates/python/module.rst

@@ -81,7 +81,7 @@ Attributes
    :hidden:
 
                      {% for attribute in visible_attributes %}
-   {{ attribute.short_name }}/index.rst
+   {{ attribute.short_name }}
                      {% endfor %}
 
                   {% endif%}
@@ -127,7 +127,18 @@ Classes
    :hidden:
 
                      {% for klass in visible_classes %}
+   {# 
+       The set own_page_types sometimes is not ordered! This changes the value of
+       its last element. Thus, the best way to check is to verify if 'function'
+       lies within the list
+       Do -> if 'function' not in own_page_types
+       Instead of -> if "class" == (own_page_types | list | last)
+   #}
+   {% if "method" not in own_page_types %}
+   {{ klass.short_name }}.rst
+   {% else %}
    {{ klass.short_name }}/index.rst
+   {% endif %}
                      {% endfor %}
 
                   {% endif %}
@@ -145,12 +156,12 @@ Classes
                {% if "function" in own_page_types or "show-module-summary" in autoapi_options %}
 Functions
 ---------
-                  {% if "class" in own_page_types %}
+                  {% if "function" in own_page_types %}
 .. toctree::
    :hidden:
 
                      {% for function in visible_functions %}
-   {{ function.short_name }}/index.rst
+   {{ function.short_name }}.rst
                      {% endfor %}
 
                   {% endif %}