python - 使用 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成为可能类和函数并不直接对应于模块作为文件的组织方式。 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