include imported functions in module documentation

Question

My code has the following directory structure:

apkg/
  __init__.py
  amod.py
  bmod.py
  cmod.py

Where apkg/__init__.py contains:

"""
effusive top-level documentation
"""
from apkg.amod import foo
from apkg.bmod import bar
from apkg.cmod import baz

And from the python repl I can successfully invoke foo, bar, and baz without knowing which submodule they're defined in:

>>> import apkg
>>> apkg.foo()
"foo"

And get their documentation:

>>> help(apkg.foo)
Help on function foo in module apkg.amod:

foo()
    Returns "foo"

But they're not advertised in apkg's documentation:

>>> help(apkg)
Help on package apkg:

NAME
    apkg - effusive top-level documentation

PACKAGE CONTENTS
    amod
    bmod
    cmod

FILE
    /path/to/apkg/__init__.py

This makes sense as a default, since I'd hardly want to include defaultdict's documentation just by doing from collections import defaultdict in apkg/__init__.py.

Is there a way to override this default, so I can tell the documentation parser to list foo, bar and baz in the FUNCTIONS section for help(apkg)?

Answer 1

According to this answer:

Documentation tools

Documentation and code autocompletion tools may (in fact, should) also inspect the __all__ to determine what names to show as available from a module.

So it's as simple as appending a single line to apkg/__init__.py

__all__ = ['foo', 'bar', 'baz']