Dari Sphinx versi 3.1 (Juni 2020), sphinx.ext.autosummary(akhirnya!) Memiliki rekursi.
Jadi tidak perlu nama kode modul keras atau mengandalkan perpustakaan pihak ke-3 seperti Sphinx AutoAPI atau Sphinx AutoPackageSummary untuk deteksi paket otomatis mereka lagi.
Paket contoh Python 3.7 untuk didokumentasikan ( lihat kode pada Github dan hasil pada ReadTheDocs ):
mytoolbox
|-- mypackage
| |-- __init__.py
| |-- foo.py
| |-- mysubpackage
| |-- __init__.py
| |-- bar.py
|-- doc
| |-- source
| |--index.rst
| |--conf.py
| |-- _templates
| |-- custom-module-template.rst
| |-- custom-class-template.rst
conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # Source code dir relative to this file
extensions = [
'sphinx.ext.autodoc', # Core library for html generation from docstrings
'sphinx.ext.autosummary', # Create neat summary tables
]
autosummary_generate = True # Turn on sphinx.ext.autosummary
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
index.rst(perhatikan :recursive:opsi baru ):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
Ini cukup untuk secara otomatis merangkum setiap modul dalam paket, betapapun bersarangnya. Untuk setiap modul, modul ini merangkum setiap atribut, fungsi, kelas dan pengecualian dalam modul itu.
Anehnya, sphinx.ext.autosummarytemplat default tidak melanjutkan untuk menghasilkan halaman dokumentasi terpisah untuk setiap atribut, fungsi, kelas dan pengecualian, dan tautan ke mereka dari tabel ringkasan. Dimungkinkan untuk memperluas templat untuk melakukan ini, seperti yang ditunjukkan di bawah ini, tetapi saya tidak dapat memahami mengapa ini bukan perilaku default - tentu itu yang diinginkan kebanyakan orang ..? Saya telah mengangkatnya sebagai permintaan fitur .
Saya harus menyalin template default secara lokal, dan kemudian menambahkannya:
- Salin
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstkemytoolbox/doc/source/_templates/custom-module-template.rst
- Salin
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstkemytoolbox/doc/source/_templates/custom-class-template.rst
Kait ke dalam custom-module-template.rstada di index.rstatas, menggunakan :template:opsi. (Hapus baris itu untuk melihat apa yang terjadi dengan menggunakan templat paket situs standar.)
custom-module-template.rst (baris tambahan dicatat di sebelah kanan):
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}
{% block attributes %}
{% if attributes %}
.. rubric:: Module Attributes
.. autosummary::
:toctree: <-- add this line
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}
.. autosummary::
:toctree: <-- add this line
:template: custom-class-template.rst <-- add this line
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block modules %}
{% if modules %}
.. rubric:: Modules
.. autosummary::
:toctree:
:template: custom-module-template.rst <-- add this line
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
custom-class-template.rst (baris tambahan dicatat di sebelah kanan):
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members: <-- add at least this line
:show-inheritance: <-- plus I want to show inheritance...
:inherited-members: <-- ...and inherited members too
{% block methods %}
.. automethod:: __init__
{% if methods %}
.. rubric:: {{ _('Methods') }}
.. autosummary::
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}
.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
lske file dan mengeditnya?