Allow autosummary to respect __all__

[Yoshanuikabundi]

Python's __all__ attribute defines the public API of a module or package. Autosummary should support this.

Feature or Bugfix

• Feature

Purpose

Python modules and packages can supply a list of names in the __all__ attribute to declare the public interface. If this is present, Autosummary should use it to determine which objects to document.

Detail

• Adds the autosummary_ignore___all__ configuration value, True by default. This anticipates a future breaking change where this will be set to False as discussed in #2021: changed autosummary to only consider elements of __all__, if present #9455
• If autosummary_ignore___all__ is False, autosummary will use the __all__ attribute to discover the module's members
• If autosummary_ignore___all__ is False but a module does not have the __all__ attribute, the previous behaviour is kept
• Regression tests have been added and updated
• The -a/--respect-__all__ command line switch has been added to autogen to support this behaviour on the CLI
• The configuration value is documented
• Currently, all submodules are documented, regardless of whether they're in __all__. This matches the behaviour of pydoc, but I think submodules may or may not be a part of the public API and should be controlled by the same mechanism. I haven't had time to track this down yet but should be able to do so tomorrow. Thoughts?

Relates

• closes autosummary ignores __all__ for modules #2021

[tk0miya]

LGTM basically. Let's go forward!

[Yoshanuikabundi]

I believe this is now ready to merge. From everything I've read, I don't think submodules are supposed to go into __all__, and it looks like that would have to be a more complicated change anyway, so it might be better to leave it to a future PR.

[Yoshanuikabundi]

Fixed those, grepped everything for any other option names I missed, and rebased on current 4.x

[tk0miya]

LGTM with nits :-)

[tk0miya]

It seems flake8 and mypy warns something. Could you check them please?

[Yoshanuikabundi]

Fixed. What are your thoughts on the submodules thing?

Currently, all submodules are documented, regardless of whether they're in all. This matches the behaviour of pydoc, but I think submodules may or may not be a part of the public API and should be controlled by the same mechanism. Thoughts?

Having thought about it I think I do want this behaviour for my projects, but I can't find clear docs on how modules should be included in __all__ - absolute path, relative path, imported and then treated as locals... Would welcome any thoughts you had! And would be happy to leave this as separately configurable behaviour for a future PR.

[tk0miya]

LGTM!

[tk0miya]

What are your thoughts on the submodules thing?

I agree it would be better to add a way to control what submodules are documented (or undocumented) on the recursive build. But I'm not sure using __all__ is better for that purpose. IMO, it does not related to the submodules.

[tk0miya]

As I commented above, controlling submodules is another topic. So I'd like to merge this. What do you think?

[Yoshanuikabundi]

Cool! I'll open an issue to discuss design of the submodules thing when I get a chance. I agree that this is ready to merge :)

[tk0miya]

Okay, merging now!

[tk0miya]

Thank you for your great work!