С версии Sphinx 3.1 (июнь 2020 г.), sphinx.ext.autosummary (наконец-то!) Появилась рекурсия.
Поэтому нет необходимости жестко кодировать имена модулей или полагаться на сторонние библиотеки, такие как Sphinx AutoAPI или Sphinx AutoPackageSummary. для автоматического определения пакетов.
Пример пакета Python 3.7 для документа ( см. Код на Github и результат на 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(обратите внимание на новую :recursive:опцию):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
Этого достаточно для автоматического суммирования каждого модуля в пакете, как бы глубоко он ни был вложен. Для каждого модуля он суммирует каждый атрибут, функцию, класс и исключение в этом модуле.
Как ни странно, по умолчанию sphinx.ext.autosummary шаблоны не генерируют отдельные страницы документации для каждого атрибута, функции, класса и исключения и ссылаются на них из сводных таблиц. Для этого можно расширить шаблоны, как показано ниже, но я не могу понять, почему это не поведение по умолчанию - конечно, это то, что большинство людей хотели бы ..? Я поднял это как запрос функции .
Мне пришлось скопировать шаблоны по умолчанию локально, а затем добавить к ним:
- копия
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstвmytoolbox/doc/source/_templates/custom-module-template.rst
- Копировать
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstвmytoolbox/doc/source/_templates/custom-class-template.rst
Крюк custom-module-template.rstв index.rstвыше, используя:template: опцию. (Удалите эту строку, чтобы увидеть, что происходит с использованием стандартных шаблонов сайтов-пакетов.)
custom-module-template.rst (дополнительные строки отмечены справа):
{{ 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 (дополнительные строки отмечены справа):
{{ 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 %}
lsк файлу и редактировать это?