如何让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:

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

我在这里发现了一个类似的问题。我试了他建议的方法，但没能奏效。

在我的例子中，我应该包括什么路径?

我的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(实际上是run_anom_detection，但名称无关紧要)。

形象2日编辑:

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

让我们有如下的文件夹结构:

└──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。

引用:

• 如何用python完成相对导入
• 第10亿次相对进口
• https://chrisyeh96.github.io/2017/08/08/definitive-guide-python-imports.html