З версії 3.1 Сфінкса 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до файлу та редагувати це?