递归使用Sphinx自动生成API文档 [英] Use Sphinx autosummary recursively to generate API documentation

问题描述

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

I want to use Sphinx's autosummary extension and templates to generate API docs recursively from docstrings. I want separate pages for each module, class, method, property and function. But it doesn't detect my templates at all. In fact, if I just remove the module.rst file from _templates/autosummary/, it renders the whole file exactly the same way as before. I've followed this SO question to the letter. If you're interested, the full repository is on GitHub.

似乎确实生成了一个不同的文件，我不得不删除docs/_autosummary才能读取新模板.但是，现在它生成带有sparse标头和description标头的文件.它不包含在{% if classes %}和{% if functions %}指令中.

It seems it does generate a different file, I had to delete docs/_autosummary for it to read the new template. However, now it generates a file with the sparse header and description header. It doesn't go into the {% if classes %} and {% if functions %} directives.

我的目录结构如下:

• 稀疏
• 文档
  • conf.py
  • index.rst
  • modules.rst
  • _templates/autosummary/module.rst
  • sparse
  • docs
    • conf.py
    • index.rst
    • modules.rst
    • _templates/autosummary/module.rst

    这是到目前为止的相关文件:

    Here are the relevant files so far:

    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.

    I also needed to go to sphinx/ext/autosummary/generate.py and set imported_members=True in the function generate_autosummary_docs.

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

    If you're not using numpydoc like me, you might need to remove the .. HACK directives.

    这篇关于递归使用Sphinx自动生成API文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！