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.)

[cmarqu]

@knuxify You could also consider using https://nedbatchelder.com/code/cog. See https://til.simonwillison.net/python/cog-to-update-help-in-readme for a writeup that uses it for rst files.

[picnixz]

I would actually support this because sometimes the output produced by autodoc does not suit well our needs, though I don't know how to properly implement this yet. We could treat those kind of directives like an autoclass directive and traverse the functions that are identified by the regex (informally, autoclass works by first autodocing the class itself, and then autodocing each of its methods).

Another issue is that the regular expression might become quite complex. For instance, it would be good if we can also skip some members because they need to have a special doc instead (also, how would we handle the body of such directive? would it be copied to all picked members?)

However, the cog alternative may seem a good alternative for generating RST content (and thankfully, RST supports comments using ..).