如何让autodoc导入本地写的包

Question

我有以下结构：

└──faulty_meter
    └── __init__.py
    └── run.py
    └── utils.py
    └── anomalous_kwh_detection
        └── __init__.py
        └── general_anomalies.py
        └── slowing_down.py
    └── docs
        └── Makefile
        └── build
        └── make.bat
        └── source
            └── conf.py
            └── index.rst

run.py 导入 utils.py 和 anomalous_kwh_detection.

中的文件

我运行狮身人面像来自docs:

sphinx-quickstart
sphinx-apidoc -o ./source ..
make html

我收到此警告：WARNING: autodoc: failed to import module 'run.py' from module 'faulty_meter'; the following exception was raised: No module named 'utils'，这意味着 autodoc 无法找到 utils.py

我发现了一个类似的问题here。我尝试了建议的方法，但无法真正发挥作用。

就我而言，我应该包括什么路径？

我的 conf.py 文件看起来像这样

import os
import sys
sys.path.insert(0, os.path.abspath('../../..'))
project = 'a'
copyright = '2021, b'
author = 'b'
release = '0.0.1'
extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon']
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

我的 index.rst 看起来像这样：

.. a documentation master file, created by
   sphinx-quickstart on Thu Aug 19 21:54:31 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to a's documentation!
=============================

.. toctree::
   :maxdepth: 6
   :caption: Contents:

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

一切正常，除了 run.py 被忽略，如警告所示。如何解决？

编辑：我附上了生成文档的示例。它正确生成了 utils 的文档，但忽略了运行（实际上是 run_anom_detection，但名称无关紧要）。

image

第二次编辑:

我将提供一个最小的复制示例：

让我们有以下文件夹结构：

└──faulty_meter
    └── __init__.py
    └── run.py
    └── utils.py
    └── anomalous_kwh_detection
        └── __init__.py
        └── general_anomalies.py
    └── docs
        └── Makefile
        └── build
        └── make.bat
        └── source
            └── conf.py
            └── index.rst

那么utils.py可以是这样

def test1(x, y):
    """
    This is just a quick test

    Parameters
    ----------
    x: array
       random array
    y: array
       another random array
    """
    return x+y

general_anomaly.py 可以像这样

def test2(x, y):
    """
    This is just a quick test

    Parameters
    ----------
    x: array
       random array
    y: array
       another random array
    """
    return x-y

和run.py可以是

import utils
from anomalous_kwh_detection import general_anomalies as ga

def test_run(x, y, z):
    """
    This is the function that is not documented
    """
    p = utils.test1(x, y)+ ga.test2(y, z)
    return p

Answer 1

这里的问题是 Python 包中 import 语句的解释。在 run.py 中，您有：

import utils

这是一个隐式相对导入，Python 3.

不支持它

如果您更改为 显式相对导入、

，它会起作用

from . import utils

或绝对导入,

import faulty_meter.utils as utils

如果添加一个点，run.py 中的另一个语句将起作用：

from .anomalous_kwh_detection import general_anomalies as ga

注意：当命令行中的 python run.py 为运行时，代码不会作为包的一部分执行，并且上面指定的导入不起作用。相反，您可以使用 python -m faulty_meter.run.

参考文献：

How to accomplish relative import in python
Relative imports for the billionth time
https://chrisyeh96.github.io/2017/08/08/definitive-guide-python-imports.html

如何让autodoc导入本地写的包

How to get autodoc to import packages that are locally written

python

python-sphinx

autodoc