#2021: changed autosummary to only consider elements of __all__, if present

[randolf-scholz]

Addresses #2021

Feature or Bugfix

• Feature
• Bugfix

Not sure if it should be considered a feature enhancement or bug fix.

Purpose

• autosummary ignores __all__ files when determining members, this PR changes the behaviour to always respect the __all__ list, if it exists.

Detail

Changed 2 iterators from

for name in dir(obj):

to

for name in getall(obj) or dir(obj):

using the sphinx.util.inspect.getall function, which returns __all__, if it exists, else None.

Relates

• autosummary ignores __all__ for modules #2021

[marscher]

Thank you, that would simplify my duties a lot!

[tk0miya]

Looks good. But we need to add an option to keep __all__ list ignored.

[randolf-scholz]

Looks good. But we need to add an option to keep __all__ list ignored.

Is this really necessary? I would be surprised if there is a single project that really wants this option.
The point is that if one adds something like the following members block to the modules template

{% block members %}
{% if members %}
.. rubric:: {{ _('Module Members') }}
.. autosummary::
  :toctree: {{ objname }}
{% for item in members %}
  {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

Then all of the otherwise hidden module members get added as well:

Who would want to see all this nonsense for every module?

[marscher]

I'd agree to that no one wants to have these kind of implementation details in the members list. However I think that since this is a change of behavior, people should be given the chance to still use the old behavior. Therefore we need a switch.

[tk0miya]

Is this really necessary? I would be surprised if there is a single project that really wants this option.

I can't say there are no projects that depend on the old behavior in the world. I agree they're very few. But this change will bring a breaking change for them. So I can't accept this change without an option.

[Yoshanuikabundi]

@randolf-scholz Hi! I need this feature and don't want it to miss the next release. I'd be happy to extend this PR to take a configuration option, but don't want to step on your toes! Please let me know if you're committed to finishing things up here, or if you don't mind me taking over.

[randolf-scholz]

@Yoshanuikabundi Hey, sorry I am super busy atm and don't really have time look into it currently. Personally, for several other reasons I also switched my projects to https://github.com/readthedocs/sphinx-autoapi.

[Yoshanuikabundi]

@randolf-scholz No worries, thanks for the update!

[marscher]

@Yoshanuikabundi I sent a PR to @randolf-scholz including the config interface already. I think it would serve as a base to make further progress. The only thing missing are proper tests for the new interface.

@randolf-scholz when you are so busy, would you like to delegate this to our hands? I dunno if or how we would be able to directly push to your forked branch, but this would simplify things a lot. Thank you!

[tk0miya]

@marscher I think #9831 is a successor of this PR. Could you check it please?

[marscher]

sorry i'm out of time right now, but will do next week. The code looks good so far.

[tk0miya]

Now I merged #9831 as a successor of this PR. Thank you for all your contributions :-)