python - How to use sphinx automodule and exposed functions in __init__

Question

I have a folder structure that looks like:

project/
    mymodule/
        __init__.py
        m1.py
        m2.py
        sub1/
            __init__.py
            s1.py
            s2.py

mymod/__init__.py:

"""The __init__ docstr"""
from m1 import *
from m2 import *

mymod/m1.py:

"""m1 doc str"""
def func1():
    """func1 docstr"""
    return 1

mymod/m2.py:

"""m2 doc str"""
def func2():
    """func2 docstr"""
    return 2

mymod/sub1/__init__.py:

"""The sub1 __init__ docstr"""
from s1 import *
from s2 import *

mymod/sub1/s1.py:

"""s1 docstr"""
def sub1():
    """sub1 docstr"""
    return 3

mymod/sub1/s2.py:

"""s2 docstr"""
def sub2():
    """sub2 docstr"""
    return 4

When I use the module directly it seems to be working as expected:

>>> import mymod
>>> from mymod import sub1
>>> mymod.func1()
1
>>> sub1.subfunc1()
3
>>> mymod.__doc__
'The __init__ docstr'
>>> mymod.func1.__doc__
'func1 docstr'

However, when I go to use the automodule in sphinx (after adding the project folder to my sys.path):

.. automodule:: mymod
    :members:

.. automodule:: mymod.sub1
    :members:

I get a page with just:

The __init__ docstr
The sub1 __init__ docstr

It seems to be ignoring the from m1 import * type statements...

But, if I copy all of the code directly into the __init__ files for each module/sub-module I get:

The __init__ docstr

mymod.func1()
func1 docstr

mymod.func2()
func2 docstr

The sub1 __init__ docstr

mymod.sub1.sub1()
sub1 docstr

mymod.sub1.sub2()
sub2 docstr

Does sphinx automodule not work with modules with these sorts of import statements in the __init__ file or am I missing a more obvious issue?

Ideally, I'd like an output like I get when putting all the code in the init (put using import statements instead).

Answer 1

It works if you add an __all__ list to the __init__.py files. For example:

"""The __init__ docstr"""

__all__ = ['func1', 'func2']

from m1 import *
from m2 import *