Document package and modules under a "submodules" heading

Closes #450

Author: AWhetter

autoapi/templates/python/module.rst

@@ -12,24 +12,10 @@
 
       {% endif %}
 
-      {% block subpackages %}
-         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
-         {% if visible_subpackages %}
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 1
-
-            {% for subpackage in visible_subpackages %}
-   {{ subpackage.include_path }}
-            {% endfor %}
-
-
-         {% endif %}
-      {% endblock %}
       {% block submodules %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
          {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
          {% if visible_submodules %}
 Submodules
 ----------

docs/changes/450.bugfix.rst

@@ -0,0 +1 @@
+Document packages and modules under a single "submodules" heading

tests/python/test_own_page_option.py

@@ -28,11 +28,9 @@ def test_package(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        subpackages = package_file.find(id="subpackages")
-        assert subpackages
-        assert subpackages.find("a", string="package.subpackage")
         submodules = package_file.find(id="submodules")
         assert submodules
+        assert submodules.find("a", string="package.subpackage")
         assert submodules.find("a", string="package.submodule")
 
         # There should not be links to the children without their own page
@@ -66,7 +64,6 @@ def test_subpackage(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        assert not subpackage_file.find(id="subpackages")
         submodules = subpackage_file.find(id="submodules")
         assert submodules
         assert submodules.find("a", string="package.subpackage.submodule")
@@ -98,7 +95,6 @@ def test_module(self, parse):
 
         # There should not be links to the children without their own page
         assert not submodule_file.find(id="submodules")
-        assert not submodule_file.find(id="subpackages")
         assert not submodule_file.find(id="attributes")
         assert not submodule_file.find(id="exceptions")
         assert not submodule_file.find(id="classes")
@@ -177,11 +173,9 @@ def test_package(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        subpackages = package_file.find(id="subpackages")
-        assert subpackages
-        assert subpackages.find("a", string="package.subpackage")
         submodules = package_file.find(id="submodules")
         assert submodules
+        assert submodules.find("a", string="package.subpackage")
         assert submodules.find("a", string="package.submodule")
         exceptions = package_file.find(id="exceptions")
         assert exceptions
@@ -230,7 +224,6 @@ def test_module(self, parse):
 
         # There should not be links to the children without their own page
         assert not submodule_file.find(id="submodules")
-        assert not submodule_file.find(id="subpackages")
         assert not submodule_file.find(id="attributes")
         assert not submodule_file.find(id="functions")
 
@@ -388,11 +381,9 @@ def test_package(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        subpackages = package_file.find(id="subpackages")
-        assert subpackages
-        assert subpackages.find("a", string="package.subpackage")
         submodules = package_file.find(id="submodules")
         assert submodules
+        assert submodules.find("a", string="package.subpackage")
         assert submodules.find("a", string="package.submodule")
         classes = package_file.find(id="classes")
         assert classes
@@ -445,7 +436,6 @@ def test_module(self, parse):
 
         # There should not be links to the children without their own page
         assert not submodule_file.find(id="submodules")
-        assert not submodule_file.find(id="subpackages")
         assert not submodule_file.find(id="attributes")
 
         # Children without their own page should be rendered on this page,
@@ -578,11 +568,9 @@ def test_package(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        subpackages = package_file.find(id="subpackages")
-        assert subpackages
-        assert subpackages.find("a", string="package.subpackage")
         submodules = package_file.find(id="submodules")
         assert submodules
+        assert submodules.find("a", string="package.subpackage")
         assert submodules.find("a", string="package.submodule")
         classes = package_file.find(id="classes")
         assert classes
@@ -635,7 +623,6 @@ def test_module(self, parse):
 
         # There should not be links to the children without their own page
         assert not submodule_file.find(id="submodules")
-        assert not submodule_file.find(id="subpackages")
         assert not submodule_file.find(id="attributes")
 
         # Children without their own page should be rendered on this page,
@@ -792,11 +779,9 @@ def test_package(self, parse):
         assert docstring.text == "This is a docstring."
 
         # There should be links to the children with their own page
-        subpackages = package_file.find(id="subpackages")
-        assert subpackages
-        assert subpackages.find("a", string="package.subpackage")
         submodules = package_file.find(id="submodules")
         assert submodules
+        assert submodules.find("a", string="package.subpackage")
         assert submodules.find("a", string="package.submodule")
         classes = package_file.find(id="classes")
         assert classes
@@ -843,7 +828,6 @@ def test_module(self, parse):
 
         # There should not be links to the children without their own page
         assert not submodule_file.find(id="submodules")
-        assert not submodule_file.find(id="subpackages")
 
         # Children without their own page should be rendered on this page,
         # and children with their own page should not be rendered on this page.