Skip to content

Commit

Permalink
Document package and modules under a "submodules" heading
Browse files Browse the repository at this point in the history 
Closes #450
  • Loading branch information
@AWhetter
AWhetter committed Oct 26, 2024
1 parent 53c2abc commit 0e9bb9b
Show file tree
Hide file tree
Showing 3 changed files with 8 additions and 37 deletions.
18 changes: 2 additions & 16 deletions autoapi/templates/python/module.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down
1 change: 1 addition & 0 deletions docs/changes/450.bugfix.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document packages and modules under a single "submodules" heading
26 changes: 5 additions & 21 deletions tests/python/test_own_page_option.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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")

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 0e9bb9b

Please sign in to comment.