如何配置 Sphinx autodoc 以记录 __init__.py 中的类？

如何解决如何配置 Sphinx autodoc 以记录 __init__.py 中的类？

我有带有 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 期间发生的那些警告吗？

感谢任何有关如何配置 Sphinx 以缩小差距的见解。

解决方法

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

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