Sphinx autodoc 不夠自動化

Question

我正在嘗試使用 Sphinx 在 Python 中記錄一個 5,000 多行的項目。 它有大約 7 個基本模塊。 據我所知，為了使用 autodoc，我需要為項目中的每個文件編寫這樣的代碼：

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

這太乏味了，因為我有很多文件。 如果我可以指定我想要記錄“mods”包，那會容易得多。 Sphinx 然后可以遞歸地遍歷包並為每個子模塊創建一個頁面。

有這樣的功能嗎？ 如果沒有，我可以編寫一個腳本來制作所有 .rst 文件，但這會占用很多時間。

Answer 1

你可以查看我制作的這個腳本。 我認為它可以幫助你。

此腳本解析目錄樹以查找 python 模塊和包，並適當地創建 ReST 文件以使用 Sphinx 創建代碼文檔。 它還創建一個模塊索引。

更新

這個腳本現在作為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 （右側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 （右側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. 在conf.py文件中啟用autosummary擴展（以及autodoc ）並將其autosummary_generate選項設置為True 。 如果您不使用自定義*.rst模板，這可能就足夠了。 否則，將您的模板目錄添加到排除列表中，否則autosummary會嘗試將它們視為輸入文件（這似乎是一個錯誤）。

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

2. 在index.rst文件的 TOC 樹中使用autosummary:: 。 在本示例中，模塊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下方是_build ）。

Answer 4

Sphinx AutoAPI正是這樣做的。

Answer 5

在每個包中， __init__.py文件可以為.. automodule:: package.module的每個部分包含.. automodule:: package.module組件。

然后你可以.. automodule:: package並且它主要做你想要的。

Answer 6

也許您正在尋找的是Epydoc和這個Sphinx 擴展。