web-dev-qa-db-ja.com

Sphinx自動集計を再帰的に使用してAPIドキュメントを生成する

Sphinxの autosummary extension および templates を使用して、docstringから再帰的にAPIドキュメントを生成したいと思います。モジュール、クラス、メソッド、プロパティ、関数ごとに個別のページが必要です。しかし、それは私のテンプレートをまったく検出しません。実際、module.rstから_templates/autosummary/ファイルを削除すると、ファイル全体が以前とまったく同じようにレンダリングされます。私は this SO question の手紙に従いました。興味があれば、- 完全なリポジトリはGitHubにあります です。

編集：別のファイルが生成されるようです。新しいテンプレートを読み取るには、docs/_autosummaryを削除する必要がありました。ただし、現在はsparseヘッダーとdescriptionヘッダーを持つファイルが生成されます。 {% if classes %}および{% if functions %}ディレクティブには含まれません。

私のディレクトリ構造は次のとおりです：

  • 疎
  • docs
    • conf.py
    • index.rst
    • modules.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 %}
pythonjinja2python-sphinxrestructuredtext
14
Hameer Abbasi

私は次のファイルを必要としました：

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に移動して、関数imported_members=Trueにgenerate_autosummary_docsを設定する必要もありました。

私のようにnumpydocを使用していない場合は、.. HACKディレクティブを削除する必要があるかもしれません。

6
Hameer Abbasi