狮身人面像自动文档不够自动化。

Question

我试图使用Sphinx在Python中记录一个5,000+行项目。它有大约7个基本模块。据我所知，为了使用autodoc，我需要为项目中的每个文件编写如下代码：

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

这太乏味了，因为我有很多文件。如果我可以指定我希望“mods”软件包被记录下来，那就容易多了。Sphinx可以递归地遍历包并为每个子模块创建一个页面。

有这样的特色吗？如果不是，我可以编写一个脚本来创建所有的.rst文件，但是这需要花费大量的时间。

Answer 1

来自狮身人面像3.1版(2020年6月)，sphinx.ext.autosummary (终于！)有自动递归。

因此，不再需要硬编码模块名或依赖第三方库(如狮身人面像AutoAPI或狮身人面像AutoPackageSummary )来自动检测包。

示例Python3.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 2

我不知道狮身人面像在提出原始问题时是否有autosummary扩展，但目前很有可能在不使用sphinx-apidoc或类似脚本的情况下设置这种类型的自动生成。下面是为我的一个项目工作的设置。

1. 在autosummary文件中启用conf.py扩展(以及autodoc)，并将其autosummary_generate选项设置为True。如果不使用自定义*.rst模板，这可能就足够了。否则，添加模板目录以排除列表，否则autosummary将尝试将它们视为输入文件(这似乎是一个错误)。 扩展= 'sphinx.ext.autodoc'，'sphinx.ext.autosummary‘autosummary_generate = True templates_path = '_templates’exclude_patterns = '_build'，'_templates‘
2. 在您的autosummary::文件中的TOC树中使用index.rst。在本例中，将自动生成模块的project.module1和project.module2文档，并将它们放在_autosummary目录中。 项目======= ..。树：：..。自动摘要:toctree：_autosummary project.module1 project.module2
3. 默认情况下，autosummary只为模块及其函数生成非常简短的摘要。若要更改此操作，可以将自定义模板文件放入_templates/autosummary/module.rst (将使用Jinja2解析)： {全名}{下划线}自动模块：：{全名}：成员：

总之，不需要将_autosummary目录保持在版本控制之下。此外，您可以将它命名为您想要的任何名称，并将其放置在源树中的任何位置(但是，将它放在_build下面将无法工作)。

Answer 3

狮身人面像AutoAPI正是这样做的。