Documenting package init imports with Sphinx

Question

I have a Python package, felling which has a method:

from felling.src.email import send_email

Following from how Pandas handles imports such as pandas.DataFrame in felling.__init__.py I have:

# felling.__init__.py
from felling.src.email import send_email

Which allows someone to import felling.src.email.send_email by using:

from felling import send_email

With this last import method being the main way I intend send_email to be imported. Nobody ever runs from pandas.core.api import DataFrame despite this being valid.

When documenting felling with Sphinx it documents send_email as felling.src.email.send_email not felling.email. I've read through Pandas docs and cannot figure how they get Sphinx to document pandas.core.api.DataFrame as pandas.DataFrame.

How can I do this?

Example `.py`

# felling.src.email

def send_email(to:str, subject:str):
    """
    Send an email

    Parameters
    ----------
    to : str
        Who should receive the email
    subject : str
        What should the emails subject be
    """
    print(to)
    print(subject)

Example `.rst`

felling methods
===============

A package for logging

felling.src.email
------------------------

.. automodule:: felling.src.email
   :members:
   :undoc-members:
   :show-inheritance:

Felling's tree

├── README.md
├── __init__.py
├── __main__.py
├── resources
│   └── logger.json
├── src
│   ├── __init__.py
│   ├── compare_logs.py
│   ├── configure_felling.py
│   └── email.py
└── version.py

Can you include an example `.py` and `.rst` and are you using intersphinx? — bad_coder, Mar 21 '21 at 08:03
I am not using intersphinx. I've added and example `.py` and `.rst` to the question, hope this helps — this_josh, Mar 21 '21 at 09:32
Have you tried `.. automodule:: felling.send_email`? It should work... — bad_coder, Mar 21 '21 at 09:41
I have and I get: ```WARNING: autodoc: failed to import data 'send_email.subject' from module 'felling'; the following exception was raised: No module named 'felling.send_email' WARNING: autodoc: failed to import data 'send_email.to' from module 'felling'; the following exception was raised: No module named 'felling.send_email' ``` `import felling.send_email` fails as send_email is a function that belongs to felling and not a module — this_josh, Mar 21 '21 at 09:59
Well, if `felling.send_email` is a function try [.. autofunction:: felling.send_email](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autofunction) instead. Assuming `felling` is a module or package, you can also try `.. automodule:: felling` to see how it goes. (Btw, edit the question to include the error/warnings). If this is your package/module also include a simple [tree](https://web.csulb.edu/~murdock/tree.html) of the files and the `__init__.py` where you are changing the module names. Some info is lacking from the question at this point. — bad_coder, Mar 21 '21 at 10:06
I thought I had tried that, if I had I must have implemented it wrong as that works! Thank you, sorry if this was a basic problem, I'm not that experienced with Sphinx. — this_josh, Mar 21 '21 at 10:14

score 3 · Accepted Answer · answered Mar 22 '21 at 08:49

Having a __init__.py file makes it possible that qualified names for classes and functions don't correspond directly to how modules are organized as files. A good example is given in this answer.

The autodoc directives import your objects as you normally would in Python. The first argument of a directive should be the fully qualified name of the object it's importing, so any name the __init__.py changes to allow an import should also be usable as an argument to the directive.

Directives - autodoc

autodoc provides several directives that are versions of the usual py:module, py:class and so forth. On parsing time, they import the corresponding module and extract the docstring of the given objects, inserting them into the page source under a suitable py:module, py:class etc. directive.

This means, in the case of the question, you could use:

.. autofunction:: felling.send_email

or

.. automodule:: felling

Documenting package __init__ imports with Sphinx

Example .py

Example .rst

Felling's tree

1 Answers1

Documenting package init imports with Sphinx

Example `.py`

Example `.rst`