Support glob match for autodoc (autoclass/autofunction/etc.)

[knuxify]

I have an API library with a single class containing methods for accessing various object types in the API. Each function is prefixed with its object type, like so:

class MyApiClass:
	"""Example API class."""

	# Foo

	def foo_get(self, id: int):
		# ...
		pass

	def foo_search(self, query: str):
		# ...
		pass

	def foo_barize(self, foo: ...):
		# ...
		pass

	# Bar

	def bar_get(self, id: int):
		# ...
		pass

	def bar_search(self, query: str):
		# ...
		pass

	def bar_bazify(self, bar: ...):
		# ...
		pass

I want to document each supported object type separately, with a separate header and description, and have all of the relevant functions grouped together. Right now, to do this, I'd have to specify every function manually:

Foo
----------

Foo description goes here.

.. autofunction:: MyApiClass.foo_get

.. autofunction:: MyApiClass.foo_search

.. autofunction:: MyApiClass.foo_barize

Bar
----------

Bar description goes here.

.. autofunction:: MyApiClass.bar_get

.. autofunction:: MyApiClass.bar_search

.. autofunction:: MyApiClass.bar_bazify

However, this means that I have to manually update the docs every time I add a new function. It would be nice if instead we could use a glob:

Foo
----------

Foo description goes here.

.. autofunction:: MyApiClass.foo_*

Bar
----------

Bar description goes here.

.. autofunction:: MyApiClass.bar_*

Describe alternatives you've considered

This could be done with some sort of automatic generator that runs before the docs are built and automatically writes out the autofunction directives.

Alternatively, a new directive could be introduced specifically to support globbing/more advanced matches (regex?).

I'm not aware of any plugins that do this (at least, I haven't found any in my limited search), hence this feature request.

[AA-Turner]

I'm very reluctant to add this. Adding a single autofunction directive is not a large burden, and when adding a function you already need to add tests, etc, so also updating a line in the documentation should be fine.

You could even add a test that scans your documentation files for every method name to ensure you haven't missed any.

The 'glob' solutions supported by Sphinx would be to use .. autoclass:: with the :members: option, or to use sphinx-apidoc, but I think neither are suitable in your case due to the desire to add custom groups within classes.

As such, I'm inclined to reject this feature request, but others may disagree with me.

A

[electric-coder]

As such, I'm inclined to reject this feature request, but others may disagree with me.

I've seen this requested before on SO (there are likely several dups here in the repo). The example does not show the added problem of keeping a previously changed .rst and adding the generation of a diff to it, so just running sphinx-apidoc after every change and before the build should be enough.

This is somewhat of a javadoc mentality to have a rigid structure without customization update after every change.

Since there's no demonstration of a sphinx-apidoc limitation, nor an MRE of making structural changes while keeping preexisting changes to a given .rst, I think the complexity outweighs the benefits but it is a popular request from beginners (I find it unlikely that a dev will want to keep headers over every declaration after a while). (I'm also left wondering if javadoc satisfies the said requirement.)