Sphinx的autosummary带有递归选项时未完全递归。

huangapple go评论59阅读模式
英文:

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.pyset_rho_anf_V_dot.py文件,以及dataresultssrc文件夹。省略号"..."表示已在此处省略的内容(目录和文件),以节省空间。]

我想创建一个摘要页面,其中包括项目中的所有文档字符串。然后,在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/fansdata/functionsdata/systems部分)。

Sphinx的autosummary带有递归选项时未完全递归。

这是否是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).

Sphinx的autosummary带有递归选项时未完全递归。

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范围下进行文档化的对象。

Sphinx的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.

Sphinx的autosummary带有递归选项时未完全递归。

huangapple
  • 本文由 发表于 2023年7月3日 18:56:31
  • 转载请务必保留本文链接:https://go.coder-hub.com/76604082.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定