Include specific imported functions in sphinx documentation

Question

Let's say that my_module has the following __init__.py:

from my_module.misc import f2

def f1(p1,p2):
    """
    My f1 function.

    :param p1: First parameter.
    :param p2: Second parameter.
    :return: Returned value.
    """
    return p1 + p2

Where the misc.py contains the following function:

def f2(p1,p2):
    """
    My f2 function.

    :param p1: First parameter.
    :param p2: Second parameter.
    :return: Returned value.
    """
    return p1 - p2

I am documenting my_module using sphinx with the following approach and f2 is not appearing in the result, is there a way to specify that it should be included?

my_module
---------

.. automodule:: my_module
   :members:
   :undoc-members:

See https://github.com/sphinx-doc/sphinx/issues/1061 and linked issues — AGN Gazer, May 29 '18 at 13:19
Also https://stackoverflow.com/q/25405110/8033585 - an opposite issue may provide some hints — AGN Gazer, May 29 '18 at 13:20
Ideally it would be preferable to select what members to include, like `f2` in this example, and not all that are imported. — Krzysztof Słowiński, May 29 '18 at 13:37
I think it should work if you add `f2.__module__ = "my_module"` in `__init__.py`. — mzjn, May 29 '18 at 17:03
Another option is to add `__all__ = ["f1", "f2"]` in `__init__.py`. — mzjn, May 30 '18 at 07:41
The second suggestion works for me, the first now does not. Could you post it as an answer so I can accept it please? — Krzysztof Słowiński, May 30 '18 at 09:05
I cannot explain why `f2.__module__ = "my_module"` does not work for you. Similar questions: https://stackoverflow.com/q/47903710/407651, https://stackoverflow.com/q/22096187/407651, https://stackoverflow.com/q/30856279/407651. — mzjn, May 30 '18 at 09:58

score 1 · Accepted Answer · answered May 30 '18 at 09:56

It works if you add an __all__ list in __init__.py.

from my_module.misc import f2

__all__ = ["f1", "f2"]

def f1(p1,p2):
    """
    My f1 function.

    :param p1: First parameter.
    :param p2: Second parameter.
    :return: Returned value.
    """
    return p1 + p2

From the Sphinx documentation:

For modules, __all__ will be respected when looking for members unless you give the ignore-module-all flag option. Without ignore-module-all, the order of the members will also be the order in __all__.

Include specific imported functions in sphinx documentation

1 Answers1