![](/img/trans.png)
[英]How can I get Sphinx autosummary to generate full API documentation for classes, as well as a *summary table* for those classes?
[英]Use Sphinx autosummary recursively to generate API documentation
我想使用 Sphinx 的自动摘要扩展和模板从文档字符串递归生成 API 文档。 我想要每个模块、类、方法、属性和函数的单独页面。 但它根本没有检测到我的模板。 事实上,如果我只是从_templates/autosummary/
删除module.rst
文件,它会以与以前完全相同的方式呈现整个文件。 我已经按照这个 SO 问题来写信了。 如果您有兴趣,完整的存储库位于 GitHub 上。
编辑:它似乎确实生成了一个不同的文件,我必须删除 docs/_autosummary 才能读取新模板。 但是,现在它生成一个带有sparse
标头和description
标头的文件。 它不会进入{% if classes %}
和{% if functions %}
指令。
我的目录结构如下:
以下是迄今为止的相关文件:
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.