Semi-automatically populate __all__ in __init__.py files

[vpratz]

This PR implements one possible solution to the problem highlighted in #290. By specifying __all__ in the relevant files, it makes explicit which modules and functions should be documented, so that only desired functions and modules are included. This also allows setting autosummary_imported_members = False, which greatly speeds up building the documentation.

It requires manual action when:

• a new public submodule is added: has to be added to the include_submodules list in the parent module
• a new __init__.py is added: must add the following boilerplate at the end of the file (number of dots before utils depends on the path):

from ..utils._docs import _add_imports_to_all

_add_imports_to_all(include_modules=[])

Please give feedback on the underlying mechanism. Is this an option we would be happy with, or should we rather try something else?

[vpratz]

@LarsKue Do you have any concerns against merging this, at least as a temporary solution? As there is now an effort to complete the docs (#340), I think the quick build times enabled by this change would be nice, as they enable fast iteration and checking of the docs. Also, while the focus is on this, we are able to detect if we missed anything that should be in __all__, should we want to keep this implementation as a permanent solution.

[paul-buerkner]

I cannot speak for Lars but I would be in favor of merging this :-) Valentin Pratz ***@***.***> schrieb am Fr., 28. Feb. 2025, 18:31:

…

@LarsKue <https://github.com/LarsKue> Do you have any concerns against merging this, at least as a temporary solution? As there is now an effort to complete the docs (#340 <#340>), I think the quick build times enabled by this change would be nice, as they enable fast iteration and checking of the docs. Also, while the focus is on this, we are able to detect if we missed anything that should be in __all__, should we want to keep this implementation as a permanent solution. — Reply to this email directly, view it on GitHub <#337 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADCW2AEOTHYS7DIES7ZHAC32SCMPJAVCNFSM6AAAAABXYMFHASVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJRGE4TGMZXGU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***> [image: vpratz]*vpratz* left a comment (bayesflow-org/bayesflow#337) <#337 (comment)> @LarsKue <https://github.com/LarsKue> Do you have any concerns against merging this, at least as a temporary solution? As there is now an effort to complete the docs (#340 <#340>), I think the quick build times enabled by this change would be nice, as they enable fast iteration and checking of the docs. Also, while the focus is on this, we are able to detect if we missed anything that should be in __all__, should we want to keep this implementation as a permanent solution. — Reply to this email directly, view it on GitHub <#337 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADCW2AEOTHYS7DIES7ZHAC32SCMPJAVCNFSM6AAAAABXYMFHASVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMOJRGE4TGMZXGU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[LarsKue]

As a temporary solution, I think it is fine for now. We should not fall into the trap of having to manually maintain __all__ though.

[paul-buerkner]

Great! Valentin, feel free to merge :-)