使用 Sphinx 记录包 init 导入

Question

我有一个Python包，感觉里面有个方法：

from felling.src.email import send_email

根据 Pandas 如何处理导入，例如 felling.__init__.py 中的 pandas.DataFrame 我有：

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

这允许某人使用以下方式导入 felling.src.email.send_email：

from felling import send_email

最后一种导入方法是我打算 send_email 导入的主要方式。尽管这是有效的，但没有人运行 from pandas.core.api import DataFrame。

当使用 Sphinx 记录 felling 时，它将 send_email 记录为 felling.src.email.send_email 而不是 felling.email。我通读了 Pandas 文档，无法理解他们如何让 Sphinx 将 pandas.core.api.DataFrame 记录为 pandas.DataFrame。

我该怎么做？

示例`.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)

示例`.rst`

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

A package for logging

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

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

弗林的树

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

Answer 1

拥有 __init__.py 文件使得 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.

成为可能

autodoc 指令像通常在 Python 中一样导入您的对象。指令的第一个参数应该是它正在导入的对象的完全限定名称，因此 __init__.py 更改为允许导入的任何名称也应该可以用作指令的参数。

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.

这意味着，在问题的情况下，您可以使用：

.. autofunction:: felling.send_email

或

.. automodule:: felling

使用 Sphinx 记录包 init 导入

Documenting package init imports with Sphinx

python

pandas

python-sphinx

autodoc

示例`.py`

示例`.rst`

弗林的树

使用 Sphinx 记录包 __init__ 导入

Documenting package __init__ imports with Sphinx

python

pandas

python-sphinx

autodoc

示例.py

示例.rst

弗林的树

使用 Sphinx 记录包 init 导入

Documenting package init imports with Sphinx

示例`.py`

示例`.rst`