web-dev-qa-db-fra.com

Utiliser la synthèse automatique Sphinx de manière récursive pour générer la documentation de l'API

Je veux utiliser les modèles d'extension automatique de Sphinx et pour générer récursivement des documents API de docstrings. Je veux des pages séparées pour chaque module, classe, méthode, propriété et fonction. Mais il ne détecte pas du tout mes modèles. En fait, si je supprime simplement le module.rst fichier de _templates/autosummary/, il restitue le fichier entier exactement de la même manière qu'auparavant. J'ai suivi cette SO question à la lettre. Si vous êtes intéressé, le référentiel complet est sur GitHub .

Edit: Il semble qu'il génère un fichier différent, j'ai dû supprimer docs/_autosummary pour qu'il puisse lire le nouveau modèle. Cependant, il génère maintenant un fichier avec l'en-tête sparse et l'en-tête description. Il n'entre pas dans le {% if classes %} et {% if functions %} directives.

Ma structure de répertoires est la suivante:

  • clairsemé
  • docs
    • conf.py
    • index.rst
    • modules.rst
    • _templates/autosummary/module.rst

Voici les fichiers pertinents à ce jour:

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 %}
pythonjinja2python-sphinxrestructuredtext
14
Hameer Abbasi

J'ai fini par avoir besoin des fichiers suivants:

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

Je devais aussi aller à sphinx/ext/autosummary/generate.py Et mettre imported_members=True dans la fonction generate_autosummary_docs.

Si vous n'utilisez pas numpydoc comme moi, vous devrez peut-être supprimer le .. HACK directives.

6
Hameer Abbasi