问题描述
我第一次尝试使用 sphinx 来创建一些不错的文档，但我在记录 __all__ 中未定义的函数和类时遇到了问题。我已经创建了我的包，以便在导入包时只将最可能需要的函数和类加载到命名空间中，我认为这是一个好主意。可能不是？
我有几乎所有类、方法、函数的文档字符串，但只有 __all__ 中列出的文档创建了文档。显然，我希望所有的类和函数都被记录下来，以便人们可以阅读它们。就目前而言，除非在 __all__ 中，否则我无法交叉引用另一个类或函数，但这种做法首先违背了我使用 __all-- 的逻辑。
是否需要在 sphinx 文件中设置一些 conf.py 设置以确保记录所有类和函数（_hidden 除外）。
目前我只有一个非常简单的index.rst：
API Documentation
=================
.. automodapi:: toolBox
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
我的 conf.py 包括这个：
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here,as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc','sphinx.ext.viewcode','sphinx.ext.todo','sphinx.ext.napoleon','sphinx_automodapi.automodapi','sphinx_automodapi.smart_resolver','sphinx.ext.autosummary','sphinx.ext.intersphinx'
]
numpydoc_show_class_members = False
# generate autosummary even if no references
autosummary_generate = True
autosummary_imported_members = False
导致问题的文件的简化示例是：
"""
Some module
"""
__all__ = ['get_times']
@dataclass
class Times:
"""
DataClass for storing time statistics.
Attributes
----------
avg : np.ndarray
Array of averages of times.
min : np.ndarray
Array of minimums of times.
max : np.ndarray
Array of maximums of times.
st_dev : np.ndarray
Array of standard deviations of times.
"""
avg: np.ndarray
min: np.ndarray
max: np.ndarray
st_dev: np.ndarray
def get_times(sim,startTime=0,endTime=1000):
"""
Get time statistics for a simulation between the provided start and end timesteps.
Parameters
----------
simulation: str
name of dataset to process
startTime : float [s]
Time at which to start processing from.
endTime : float [s]
Time at which to stop processing at.
Returns
-------
RT : :any:`Times` object
Statistics of times.
"""
pass
# function operation not relevant here!
在此示例中，除非有人明确执行导入，否则我不希望 Times 类自动导入到命名空间中。然而，它仍然应该被记录下来。当我只列出 get_times 和其他函数时，Times 类没有被记录，任何交叉引用都不起作用，只是测试格式发生了变化。
显然，如果我去掉 __all__ 语句，它可以正常工作，但我想保留该功能，并且仍然创建包含所有内容的文档。
我想我遗漏了一些东西，但 sphinx 及其所有选项很复杂，但全自动文档的示例非常基本，似乎没有涵盖此类内容。希望得到一些有关解决此问题的指导。
解决方法
暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！
如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。
小编邮箱:dio#foxmail.com (将#修改为@）