Use Sphinx autosummary recursivamente para generar documentación API

Quiero usar la extensión y las plantillas de resumen automático de Sphinx para generar documentos API de forma recursiva a partir de cadenas de documentos. Quiero páginas separadas para cada módulo, clase, método, propiedad y función. Pero no detecta mis plantillas en absoluto. De hecho, si simplemente module.rst archivo module.rst de _templates/autosummary/ , el archivo completo se reproduce exactamente de la misma manera que antes. He seguido esta pregunta tan a la carta. Si estás interesado, el repository completo está en GitHub .

Edición: parece que genera un archivo diferente, tuve que eliminar docs / _autosummary para que lea la nueva plantilla. Sin embargo, ahora genera un archivo con el encabezado sparse y el encabezado de description . No entra en las directivas {% if classes %} y {% if functions %} .

Mi estructura de directorios es la siguiente:

  • escaso
  • docs
    • conf.py
    • index.rst
    • módulos.rst
    • _templates / autosummary / module.rst

Aquí están los archivos relevantes hasta el momento:

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 %} 

Terminé necesitando los siguientes archivos:

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 }} 

También tenía que ir a sphinx/ext/autosummary/generate.py y configurar sphinx/ext/autosummary/generate.py imported_members=True en la función generate_autosummary_docs .

Si no está utilizando numpydoc como yo, es posible que deba eliminar las directivas .. HACK .