如何配置 Sphinx autodoc 以在 __init__.py 中记录 类?
How to configure Sphinx autodoc to document classes in __init__.py?
我有 Python 代码和 NumPy 文档字符串。设法将 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 个文件: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
文件中的 classes/methods 文档字符串?我应该关注 make html
期间发生的那些警告吗?
感谢任何关于如何配置 Sphinx 以缩小差距的见解。
下面的 sys.path
适用于所有 subpackages/modules 除了只有 __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
我有 Python 代码和 NumPy 文档字符串。设法将 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 个文件: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
文件中的 classes/methods 文档字符串?我应该关注 make html
期间发生的那些警告吗?
感谢任何关于如何配置 Sphinx 以缩小差距的见解。
下面的 sys.path
适用于所有 subpackages/modules 除了只有 __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