英文:
Sphinx's autosummary with recursive option is not being fully recursive
问题
我正在使用Sphinx来文档化一个Python项目,该项目的结构如下所示。
calculator
| set_rho_and_f.py
| set_rho_and_V_dot.py
|
├───data
│ ├───fans
│ │ ...
│ │
│ ├───functions
│ │ ...
│ │
│ └───systems
│ ...
|
├───docs
│ ├───build
| | ...
| |
│ └───source
| ...
|
├───results
| ...
│
└───src
fans.py
functions.py
systems.py
[注意:编程项目包括set_rho_and_f.py
和set_rho_anf_V_dot.py
文件,以及data
、results
和src
文件夹。省略号"..."表示已在此处省略的内容(目录和文件),以节省空间。]
我想创建一个摘要页面,其中包括项目中的所有文档字符串。然后,在conf.py
文件中,我添加了autosummary
扩展:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary'
]
autosummary_generate = True
在摘要的reStructuredText文件中,我写道:
Summary
=======
.. autosummary::
:toctree: _autosummary
:recursive:
data
results
src
set_rho_and_f
set_rho_and_V_dot
在执行make html
后,当获取HTML文件时,我发现尽管autosummary
可以处理文件夹内的文件(只需查看下面的图片中的src
部分),但它无法处理文件夹内子文件夹的文件(只需查看下面的图片中的data
部分,缺少了data/fans
、data/functions
和data/systems
部分)。
这是否是autosummary
指令的典型行为?是否有任何选项可以使其确实浏览整个内容?
英文:
I am using Sphinx to document a Python project, which has the structure tree depicted below.
calculator
| set_rho_and_f.py
| set_rho_and_V_dot.py
|
├───data
│ ├───fans
│ │ ...
│ │
│ ├───functions
│ │ ...
│ │
│ └───systems
│ ...
|
├───docs
│ ├───build
| | ...
| |
│ └───source
| ...
|
├───results
| ...
│
└───src
fans.py
functions.py
systems.py
[Note: The coding project comprises set_rho_and_f.py
and set_rho_anf_V_dot.py
files, and data
, results
and src
folders. The ellipses "..." represent content (directories and files) that has been herein omitted for the sake of compactness.]
I wanted to create a summary page using all docstrings in the project. In conf.py
file I then added the autosummary
extension:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary'
]
autosummary_generate = True
And in the reStructuredText file for the summary, I wrote
Summary
=======
.. autosummary::
:toctree: _autosummary
:recursive:
data
results
src
set_rho_and_f
set_rho_and_V_dot
When getting an HTML file after doing make html
, I experienced that even though autosummary
can go through files inside a folder (just look at src
section in the picture below) it cannot go through files inside subfolders of a folder (just look at data
section in the picture below, which is missing data/fans
, data/functions
and data/systems
sections).
Is this a typical behaviour of the autosummary
directive? Is there any option to make it indeed go through the whole content?
答案1
得分: 0
自答:
在查看了James Leedham的答案中提到的Git Hub存储库,以了解如何使用Sphinx自动递归文档化所有内容后,我发现通过在子目录中添加一个__init__.py
文件,相应的内容将包括在由autosummary
生成的摘要中(如下图所示)。
看起来,这种方式使autosummary
将子目录解释为包,然后将其解析为可以在autosummary
范围下进行文档化的对象。
英文:
Self-answering:
After having a look at the Git Hub repository mentioned in James Leedham' answer for how to automatically document all content recursively with Sphinx, I found out that by adding an __init__.py
file to the subdirectories, the respective content is included in the summary generated by autosummary
(as shown in the picture below).
It seems like that in this way autosummary
interpreted the subdirectories as packages, which are then parsed as objects that may be documented under the autosummary
scope.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论