Ab Sphinx Version 3.1 (Juni 2020) hat sphinx.ext.autosummary(endlich!) Rekursion.
Sie müssen also keine Modulnamen mehr fest codieren oder sich für die automatische Paketerkennung auf Bibliotheken von Drittanbietern wie Sphinx AutoAPI oder Sphinx AutoPackageSummary verlassen .
Beispiel für ein zu dokumentierendes Python 3.7-Paket ( siehe Code in Github und Ergebnis in 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(Neue :recursive:Option beachten ):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
Dies reicht aus, um jedes Modul im Paket automatisch zusammenzufassen, auch wenn es tief verschachtelt ist. Für jedes Modul werden dann alle Attribute, Funktionen, Klassen und Ausnahmen in diesem Modul zusammengefasst.
Seltsamerweise sphinx.ext.autosummarygenerieren die Standardvorlagen jedoch keine separaten Dokumentationsseiten für jedes Attribut, jede Funktion, jede Klasse und jede Ausnahme und verknüpfen sie aus den Übersichtstabellen. Es ist möglich, die Vorlagen zu erweitern, um dies zu tun, wie unten gezeigt, aber ich kann nicht verstehen, warum dies nicht das Standardverhalten ist - sicherlich ist es das, was die meisten Leute wollen würden ..? Ich habe es als Feature-Anfrage angesprochen .
Ich musste die Standardvorlagen lokal kopieren und dann hinzufügen:
- Kopieren
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstnachmytoolbox/doc/source/_templates/custom-module-template.rst
- Kopieren
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstnachmytoolbox/doc/source/_templates/custom-class-template.rst
Der Haken in custom-module-template.rstist index.rstoben mit der :template:Option. (Löschen Sie diese Zeile, um zu sehen, was mit den Standardvorlagen für Site-Pakete geschieht.)
custom-module-template.rst (zusätzliche Zeilen rechts):
{{ 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 (zusätzliche Zeilen rechts):
{{ 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 %}
lszu einer Datei zu routen und diese zu bearbeiten?