Archives
/
sphinx-autoapi
mirror of https://github.com/readthedocs/sphinx-autoapi
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Recursive rendering of children with their own page

Browse Source
pull/394/merge
Jorge Martinez 4 months ago committed by Ashley Whetter
parent 93fb571a7e
commit 2a603b8ac0
8 changed files with 121 additions and 219 deletions
Show Stats Download Patch File Download Diff File

47
autoapi/mappers/base.py
Unescape Escape View File

@ -327,6 +327,50 @@ class SphinxMapperBase:
"""
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 @@ class SphinxMapperBase:
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)

41
autoapi/templates/python/class.rst
Unescape Escape View File

@ -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 %}

17
autoapi/templates/python/module.rst
Unescape Escape View File

@ -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 %}

34
tests/python/pypackageexample/autoapi/example/_private_module/index.rst
Unescape Escape View File

@ -1,34 +0,0 @@
:py:mod:`example._private_module`
=================================
.. py:module:: example._private_module
Module Contents
---------------
Classes
~~~~~~~
.. autoapisummary::
example._private_module.PrivateClass
.. py:class:: PrivateClass
Bases: :py:obj:`object`
A private class with public facing methods.
.. py:method:: public_method()
This is public.

110
tests/python/pypackageexample/autoapi/example/foo/index.rst
Unescape Escape View File

@ -1,110 +0,0 @@
:py:mod:`example.foo`
=====================
.. py:module:: example.foo
.. autoapi-nested-parse::
Example module
This is a description
Module Contents
---------------
Classes
~~~~~~~
.. autoapisummary::
example.foo.Foo
.. py:class:: Foo
Bases: :py:obj:`object`
.. py:class:: Meta
Bases: :py:obj:`object`
A nested class just to test things out
.. py:method:: foo()
:classmethod:
The foo class method
.. py:attribute:: class_var
:value: 42
.. py:attribute:: another_class_var
:value: 42
Another class var docstring
.. py:method:: method_okay(foo=None, bar=None)
This method should parse okay
.. py:method:: method_multiline(foo=None, bar=None, baz=None)
This is on multiple lines, but should parse okay too
pydocstyle gives us lines of source. Test if this means that multiline
definitions are covered in the way we're anticipating here
.. py:method:: method_tricky(foo=None, bar=dict(foo=1, bar=2))
This will likely fail our argument testing
We parse naively on commas, so the nested dictionary will throw this off
.. py:method:: method_sphinx_docs(foo, bar=0)
This method is documented with sphinx style docstrings.
:param foo: The first argument.
:type foo: int
:param int bar: The second argument.
:returns: The sum of foo and bar.
:rtype: int
.. py:method:: method_google_docs(foo, bar=0)
This method is documented with google style docstrings.
Args:
foo (int): The first argument.
bar (int): The second argument.
Returns:
int: The sum of foo and bar.

40
tests/python/pypackageexample/autoapi/example/index.rst
Unescape Escape View File

@ -1,40 +0,0 @@
:py:mod:`example`
=================
.. py:module:: example
.. autoapi-nested-parse::
This is a docstring.
Submodules
----------
.. toctree::
:titlesonly:
:maxdepth: 1
_private_module/index.rst
foo/index.rst
Package Contents
----------------
Functions
~~~~~~~~~
.. autoapisummary::
example.module_level_function
.. py:function:: module_level_function(foo, bar)
A module level method

11
tests/python/pypackageexample/autoapi/index.rst
Unescape Escape View File

@ -1,11 +0,0 @@
API Reference
=============
This page contains auto-generated API reference documentation [#f1]_.
.. toctree::
:titlesonly:
/autoapi/example/index
.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

40
tests/python/test_pyintegration.py
Unescape Escape View File

@ -1226,8 +1226,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
# subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
# subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1252,8 +1252,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
#subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
#subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1281,8 +1281,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
#subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
#subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1291,8 +1291,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
error_path = "_build/html/autoapi/example/foo/FooError.html"
error_file = parse(error_path)
#error_path = "_build/html/autoapi/example/foo/FooError.html"
#error_file = parse(error_path)
# TODO: Look for expected contents
@ -1318,8 +1318,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
# subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
# subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1328,17 +1328,17 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
error_path = "_build/html/autoapi/example/foo/FooError.html"
error_file = parse(error_path)
# error_path = "_build/html/autoapi/example/foo/FooError.html"
# error_file = parse(error_path)
# TODO: Look for expected contents
foo_path = "_build/html/autoapi/example/foo/Foo.html"
foo_path = "_build/html/autoapi/example/foo/Foo/index.html"
foo_file = parse(foo_path)
# TODO: Look for expected contents
func_path = "_build/html/autoapi/example/foo/module_level_function.html"
func_path = "_build/html/autoapi/example/module_level_function.html"
func_file = parse(func_path)
# TODO: Look for expected contents
@ -1359,8 +1359,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
# subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
# subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1404,8 +1404,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
# subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
# subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents
@ -1459,8 +1459,8 @@ class TestOwnPageLevel:
# TODO: Look for expected contents
subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
subpackage_file = parse(subpackage_path)
# subpackage_path = "_build/html/autoapi/example/subpackage/index.html"
# subpackage_file = parse(subpackage_path)
# TODO: Look for expected contents

Write Preview
Loading…
Cancel
Save