如何将Sphinx autodoc配置为在__init__.py中记录类

Question

我有带NumPy文档字符串的Python代码。设法将Sphinx用于API文档，但是__init__.py文件中的类未成功文档化。

示例：xxx/__init__.py

from __future__ import annotations
import sys
import re
from typing import Iterator, ...
import pyparsing as p
__all__ = ['Xxx']
class XxxData:
"""It is a class XxxData."""
def __init__(self):
self.data = dict()
def get_foo(self, foo) -> str:
"""Get foo bar.

Parameters
----------
foo : str
It is just a string.
Returns
-------
str
It is just a string.
"""
return f'{foo} bar'
class Xxx():
"""It is a class Xxx."""
def __init__(self):
super().__init__()
self._something = 'something'
def parse_bar(self, bar) -> XxxData:
"""Parse bar.
Parameters
----------
bar : str
It is just a string.
Returns
-------
XxxData
It is a return object of XxxData.
"""
print(f'Hello {bar}')
data = XxxData()
return data

样品conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',       # Core library for html generation from docstrings
'sphinx.ext.autosummary',   # Create neat summary tables
'sphinx.ext.napoleon',      # Support for NumPy and Google style docstrings
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary
autodoc_default_options = {
'show-inheritance': False,
'members': True,
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__'
}
autoclass_content = 'both'

我还编写了一个函数，以确保sys.path附加所有必需的依赖项。

docs
|-Makefile
|-build
|-make.bat
|-source
|-_static
|-_templates
|-conf.py
|-index.rst
packages
|-pss
|-src/dd
|-ps
|-xxx
|-__init__.py

下面的sphinx-apidoc命令自动创建了3个rst文件：source/api/ps.rst、source/api/ps.xxx.rst、source/api/modules.rst

sphinx-apidoc -o source/api/ ../packages/pss/src/dd/ps/ --implicit-namespaces -e -M -P

样品source/api/ps.xxx.rst:

ps.xxx package
==============
.. automodule:: ps.xxx
:members:
:undoc-members:
:show-inheritance:
:private-members:

make html构建成功，但出现以下警告：

WARNING: autodoc: failed to import module 'xxx' from module 'ps'; the following exception was raised:
No module named 'ps.xxx'; 'ps' is not a package

HMTL页面呈现为空内容。我希望看到__init__.py(上面的示例文件(中的文档字符串被记录下来，但没有发生。

从技术上讲，Sphinx是否适用于__init__.py文件中的类/方法文档字符串？我应该关心make html期间发生的那些警告吗？

感谢您对如何配置狮身人面像以缩小差距的任何见解。

Answer 1

下面的sys.path适用于所有子包/模块，只有__init__.py文件的模块除外。我使用../..是因为conf.py在顶级python源文件文件夹下面有两个层次结构。

sys.path.insert(0, os.path.abspath('../..'))

通过将../../packages/pss/src/dd显式地附加到sys.path，基于问题的定义示例，解决了只有__init__.py文件的模块的问题。

sys.path.insert(0, os.path.abspath('../../packages/pss/src/dd'))

显然，必须解决所有报告的警告，才能按预期提供文档。

WARNING: autodoc: failed to import module 'xxx' from module 'ps'; the following exception was raised:
No module named 'ps.xxx'; 'ps' is not a package