Sphinx autodoc不够自动化

Question

我正在尝试使用Sphinx来记录Python中的5000多行项目.它有大约7个基本模块.据我所知,为了使用autodoc我需要为我的项目中的每个文件编写这样的代码:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

这太繁琐了,因为我有很多文件.如果我能指定我想要记录'mods'包,那将会容易得多.然后,Sphinx可以递归地遍历包并为每个子模块创建一个页面.

有这样的功能吗？如果没有,我可以写一个脚本来制作所有的.rst文件,但这会花费很多时间.

Answer 1

您可以查看我制作的脚本.我认为它可以帮到你.

此脚本解析目录树以查找python模块和包,并相应地创建ReST文件以使用Sphinx创建代码文档.它还创建了一个模块索引.

UPDATE

此脚本现在是apidoc的Sphinx 1.1的一部分.

Answer 2

从 Sphinx 3.1 版（2020 年 6 月）开始，sphinx.ext.autosummary（终于！）具有自动递归。

因此，不再需要硬编码模块名称或依赖第 3 方库（如Sphinx AutoAPI或Sphinx AutoPackageSummary）来进行自动包检测。

要记录的示例 Python 3.7 包（参见 Github上的代码和ReadTheDocs上的结果）：

mytoolbox
|-- mypackage
|   |-- __init__.py
|   |-- foo.py
|   |-- mysubpackage
|       |-- __init__.py
|       |-- bar.py
|-- doc
|   |-- source
|       |--index.rst
|       |--conf.py
|       |-- _templates
|           |-- custom-module-template.rst
|           |-- custom-class-template.rst

conf.py：

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file

extensions = [
    'sphinx.ext.autodoc',  # Core library for html generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

index.rst（注意新:recursive:选项）：

Welcome to My Toolbox
=====================

Some words.

.. autosummary::
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   mypackage

这足以自动总结包中的每个模块，无论嵌套有多深。对于每个模块，它然后总结该模块中的每个属性、函数、类和异常。

但奇怪的是，默认sphinx.ext.autosummary模板不会继续为每个属性、函数、类和异常生成单独的文档页面，并从汇总表链接到它们。可以扩展模板来做到这一点，如下所示，但我不明白为什么这不是默认行为 - 这肯定是大多数人想要的......？我已将其作为功能请求提出。

我不得不在本地复制默认模板，然后添加到它们中：

• 复制site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst到mytoolbox/doc/source/_templates/custom-module-template.rst
• 复制site-packages/sphinx/ext/autosummary/templates/autosummary/class.rst到mytoolbox/doc/source/_templates/custom-class-template.rst

钩入custom-module-template.rst在index.rst上面，使用:template:选项。（删除该行以查看使用默认站点包模板会发生什么。）

custom-module-template.rst （右侧标注的附加行）：

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
  
   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:                                          <-- add this line
      :template: custom-class-template.rst               <-- add this line
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst                 <-- add this line
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

custom-class-template.rst （右侧标注的附加行）：

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:                                    <-- add at least this line
   :show-inheritance:                           <-- plus I want to show inheritance...
   :inherited-members:                          <-- ...and inherited members too

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

Answer 3

我不知道Sphinx autosummary在询问原始问题的时候是否有扩展,但是现在很有可能在没有使用sphinx-apidoc或类似脚本的情况下设置这种类型的自动生成.下面有一些设置适用于我的一个项目.

1. 在文件中启用autosummary扩展(以及autodoc)conf.py并将其autosummary_generate选项设置为True.如果您不使用自定义*.rst模板,这可能就足够了.否则,将模板目录添加到排除列表,或者autosummary尝试将它们视为输入文件(这似乎是一个错误).

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
   autosummary_generate = True
   templates_path = [ '_templates' ]
   exclude_patterns = ['_build', '_templates']
   

2. autosummary::在index.rst文件中的TOC树中使用.在用于模块此示例中的文档project.module1和project.module2将自动生成并放入_autosummary目录.

   PROJECT
   =======
   
   .. toctree::
   
   .. autosummary::
      :toctree: _autosummary
   
      project.module1
      project.module2
   

3. 默认情况下,autosummary只会为模块及其功能生成非常短的摘要.要更改它,您可以将自定义模板文件放入_templates/autosummary/module.rst(将使用Jinja2进行解析):

   {{ fullname }}
   {{ underline }}
   
   .. automodule:: {{ fullname }}
       :members:
   

总之,没有必要将_autosummary目录保持在版本控制之下.此外,您可以将其命名为任何名称,并将其放置在源树中的任何位置(_build尽管如此,将其放在下面也不起作用).

Answer 4

Sphinx AutoAPI正是这样做的。

Answer 5

在每个包中,__init__.py文件可以包含.. automodule:: package.module包的每个部分.

然后你可以.. automodule:: package,它主要做你想要的.