Python: how to embed all docstring help at package level help menu?

Question

What I mean to ask is:

• TLDR: how do I have my package's help include all underlying docstrings?
• I have created a package. That package has all the proper __init__.py files and all the proper docstrings (module, function, class, and method level docstrings). However, when I perform help(mypackage), the only help provided is the help provided at that top level __init__.py module.

Often package-level help does not include all of the underlying docstrings, but sometimes it does.

I want to make sure that I am embedding all of the underlying docstrings.

---

For instance, within the numpy package all underlying docstrings are available in the help at the command prompt, even though they are not provided at the top-level __init__.py.

I.e., I can type

>>> help(numpy)

and see all of the documentation, including documentation defined outside of the dunder init module.

However, many other packages, including popular ones like the pandas package do not capture all of the underlying documentation.

I.e., typing

>>> help(pandas)

only provides me the documentation defined in __init__.py.

I want to create package-level documentation mirroring how numpy does it.

---

I have tried to look through numpy to see how it is performing this magic, with no luck. I have performed Google searches, but it seems there is no way to phrase this question and get any decent links back.

Answer 1

numpy shows you documentation on classes and functions defined outside __init__.py module because of adding their names to __all__ variable in __init__.py. Try to comment lines 169-173 (don't forget to uncomment!):

#__all__.extend(['__version__', 'show_config'])
#__all__.extend(core.__all__)
#__all__.extend(_mat.__all__)
#__all__.extend(lib.__all__)
#__all__.extend(['linalg', 'fft', 'random', 'ctypeslib', 'ma'])

After doing this output of help(numpy) will be very limited.

Also let's reproduce this behaviour. Starting from '/some/path', create folder folder, file named file.py inside it with the following content:

class Class:
    """Class docstring"""

And __init__.py:

from .file import *

Now let's see the help:

/some/path$ python3.5
>>> import folder
>>> help(folder)

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

FILE
    /some/path/folder/__init__.py

And now add this line to __init__.py:

__all__ = ['Class']

After reimporting folder the command help(folder) will contain information about class Class which includes your docstring:

Help on package folder:

NAME
    folder

PACKAGE CONTENTS
    file

CLASSES
    builtins.object
        folder.file.Class

    class Class(builtins.object)
     |  Class docstring
     |  
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

DATA
    __all__ = ['Class']

FILE
    /some/path/folder/__init__.py