首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >问答首页 >如何在__init__.py中将Sphinx autodoc配置为文档类?

如何在__init__.py中将Sphinx autodoc配置为文档类?
EN

Stack Overflow用户
提问于 2021-06-12 11:22:19
回答 1查看 512关注 0票数 0

我有带有NumPy文档字符串的Python代码。设法将Sphinx用于应用程序接口文档,但是,__init__.py文件中的类没有成功记录。

示例:xxx/__init__.py

代码语言:javascript
运行
复制
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

代码语言:javascript
运行
复制
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'

代码语言:javascript
运行
复制
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.rstsource/api/ps.xxx.rstsource/api/modules.rst

代码语言:javascript
运行
复制
sphinx-apidoc -o source/api/ ../packages/pss/src/dd/ps/ --implicit-namespaces -e -M -P

示例source/api/ps.xxx.rst

代码语言:javascript
运行
复制
ps.xxx package
==============

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

make html生成成功,但出现以下警告:

代码语言:javascript
运行
复制
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 (上面的示例文件)的文档字符串被记录下来,但是没有发生。

EN

回答 1

Stack Overflow用户

发布于 2021-06-17 06:37:44

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

代码语言:javascript
运行
复制
sys.path.insert(0, os.path.abspath('../..'))

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

代码语言:javascript
运行
复制
sys.path.insert(0, os.path.abspath('../../packages/pss/src/dd'))

显然,必须处理所有报告的警告,才能使文档按预期呈现。

代码语言:javascript
运行
复制
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
票数 0
EN
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://stackoverflow.com/questions/67945351

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档