Allow the choice of classes having their own page

[AWhetter]

In a project that contains few functions and many classes with a lot of methods, it might be desirable to be able to have classes create rst files rather than modules or in addition to modules. An example of such documentation would be the PySide documentation.
We need to add a new option to support this behaviour. I think it's fine for it to be specific to having Python classes in particular produce new pages, rather than it being a list where you define which type of objects you want to create new pages. I can't think of a use case where you would want a single function or a single module level attribute per page. Module pages can already by turned off by skipping them with the autoapi-skip-member event.
It's likely that the templates would need to change to make this behaviour make sense, but it's fine for us to only add the option and expect the user to customise their own templates.

[astrojuanlu]

I came here to report this issue.

This is the behavior of sphinx.ext.autosummary, and therefore for people migrating from it, it would be nice to have an option to carry the same behavior to sphinx-autoapi. Otherwise, migrating necessarily implies breaking all the URLs, which is far from ideal.

This is the part of the module.rst template that renders the objects themselves:

sphinx-autoapi/autoapi/templates/python/module.rst

Lines 110 to 112 in 85739d5

	{% for obj_item in visible_children %}
	{{ obj_item.render()|indent(0) }}
	{% endfor %}

[raphaelquast]

Hey, I just ended up here after hours of trying to get unique files for each object of a module...
(using sphinx-autosummary with this templates: https://stackoverflow.com/a/62613202/9703451)

Is there already an existing workaround that can be used to tell sphinx-autoapi to create unique files for each
object of a module? (e.g. can this even be done with a nicely configured template or would this require actual changes in sphinx-autoapi)

In my opinion, having a unique page for each object would make the docs much less overwhelming...

[jorgepiloto]

At PyAnsys we would like to use this feature. Thus, we are more than happy to contribute and develop it, although we may need some guidance @AWhetter.

For the time being, we will update our class.rst theme so that at least each class shows up in the table of contents for the current page.

However, we would prefer to have a page per class as most of our APIs are massive. This would improve readability and avoid having long and huge index.rst pages.

[jorgepiloto]

After taking a look to the source code, it looks like this is the method in charge of creating the doc source files prior Sphinx rendering:

sphinx-autoapi/autoapi/mappers/base.py

Lines 310 to 329 in 92437c9

	def output_rst(self, root, source_suffix):
	for _, obj in sphinx.util.status_iterator(
	self.objects.items(),
	colorize("bold", "[AutoAPI] ") + "Rendering Data... ",
	length=len(self.objects),
	verbosity=1,
	stringify_func=(lambda x: x[0]),
	):
	rst = obj.render()
	if not rst:
	continue
	detail_dir = obj.include_dir(root=root)
	ensuredir(detail_dir)
	path = os.path.join(detail_dir, f"index{source_suffix}")
	with open(path, "wb+") as detail_file:
	detail_file.write(rst.encode("utf-8"))
	if self.app.config.autoapi_add_toctree_entry:
	self._output_top_rst(root)

Maybe, we could add a second loop if enabled through autoapi configuration to generate files for each module object:

# conf.py
autoapi_render_in_single_page = ["class", "function"]

As said before, any guidance is more than welcome, Ashley 👍🏼

[AWhetter]

Closing as implemented.