繁体   English   中英

递归使用 Sphinx 自动摘要生成 API 文档

[英]Use Sphinx autosummary recursively to generate API documentation

我想使用 Sphinx 的自动摘要扩展模板从文档字符串递归生成 API 文档。 我想要每个模块、类、方法、属性和函数的单独页面。 但它根本没有检测到我的模板。 事实上,如果我只是从_templates/autosummary/删除module.rst文件,它会以与以前完全相同的方式呈现整个文件。 我已经按照这个 SO 问题来写信了。 如果您有兴趣,完整的存储库位于 GitHub 上

编辑:它似乎确实生成了一个不同的文件,我必须删除 docs/_autosummary 才能读取新模板。 但是,现在它生成一个带有sparse标头和description标头的文件。 它不会进入{% if classes %}{% if functions %}指令。

我的目录结构如下:

  • 稀疏
  • 文档
    • 配置文件
    • 索引.rst
    • 模块.rst
    • _templates/autosummary/module.rst

以下是迄今为止的相关文件:

index.rst

.. sparse documentation master file, created by
   sphinx-quickstart on Fri Dec 29 20:58:03 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sparse's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

modules.rst

API Reference
=============

Modules
-------

.. autosummary::
   :toctree: _autosummary

   sparse

_templates/autosummary/module.rst

{{ fullname | escape | underline }}

Description
-----------

.. automodule:: {{ fullname | escape }}

{% if classes %}
Classes
-------
.. autosummary:
    :toctree: _autosummary

    {% for class in classes %}
        {{ class }}
    {% endfor %}

{% endif %}

{% if functions %}
Functions
---------
.. autosummary:
    :toctree: _autosummary

    {% for function in functions %}
        {{ function }}
    {% endfor %}

{% endif %}

我最终需要以下文件:

modules.rst

API Reference
=============

.. rubric:: Modules

.. autosummary::
   :toctree: generated

   sparse

_templates/autosummary/module.rst

{{ fullname | escape | underline }}

.. rubric:: Description

.. automodule:: {{ fullname }}

.. currentmodule:: {{ fullname }}

{% if classes %}
.. rubric:: Classes

.. autosummary::
    :toctree: .
    {% for class in classes %}
    {{ class }}
    {% endfor %}

{% endif %}

{% if functions %}
.. rubric:: Functions

.. autosummary::
    :toctree: .
    {% for function in functions %}
    {{ function }}
    {% endfor %}

{% endif %}

_templates/autosummary/class.rst

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

   {% block methods %}
   {% block attributes %}
   {% if attributes %}
   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
      .. autosummary::
         :toctree:
      {% for item in all_attributes %}
         {%- if not item.startswith('_') %}
         {{ name }}.{{ item }}
         {%- endif -%}
      {%- endfor %}
   {% endif %}
   {% endblock %}

   {% if methods %}
   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
      .. autosummary::
         :toctree:
      {% for item in all_methods %}
         {%- if not item.startswith('_') or item in ['__call__'] %}
         {{ name }}.{{ item }}
         {%- endif -%}
      {%- endfor %}
   {% endif %}
   {% endblock %}

_templates/autosummary/base.rst

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ objname }}

我还需要去sphinx/ext/autosummary/generate.py并在函数generate_autosummary_docs设置imported_members=True

如果您不像我那样使用numpydoc ,则可能需要删除.. HACK指令。

从 Sphinx 3.1 版(2020 年 6 月)开始,您可以使用新的:recursive:选项让sphinx.ext.autosummary自动检测包中的每个模块,无论嵌套sphinx.ext.autosummary深,并自动为每个属性、类、函数和该模块中的异常。

在此处查看我的答案: https : //stackoverflow.com/a/62613202/12014259

暂无
暂无

声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.

 
粤ICP备18138465号  © 2020-2024 STACKOOM.COM