Od wersji 3.1 Sphinx (czerwiec 2020) sphinx.ext.autosummary(w końcu!) Ma rekursję.
Nie trzeba więc już na stałe kodować nazw modułów ani polegać na bibliotekach innych firm, takich jak Sphinx AutoAPI lub Sphinx AutoPackageSummary do automatycznego wykrywania pakietów.
Przykładowy pakiet Pythona 3.7 do udokumentowania ( zobacz kod na Github i wynik w 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(uwaga na nową :recursive:opcję):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
To wystarczy, aby automatycznie podsumować każdy moduł w pakiecie, nawet jeśli jest głęboko zagnieżdżony. Dla każdego modułu podsumowuje następnie każdy atrybut, funkcję, klasę i wyjątek w tym module.
Co dziwne, domyślne sphinx.ext.autosummaryszablony nie generują oddzielnych stron dokumentacji dla każdego atrybutu, funkcji, klasy i wyjątku oraz nie zawierają linków do nich z tabel podsumowań. Możliwe jest rozszerzenie szablonów, aby to zrobić, jak pokazano poniżej, ale nie mogę zrozumieć, dlaczego nie jest to domyślne zachowanie - z pewnością tego chciałaby większość ludzi ...? Podniosłem to jako prośbę o funkcję .
Musiałem lokalnie skopiować domyślne szablony, a następnie dodać do nich:
- Skopiuj
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstdomytoolbox/doc/source/_templates/custom-module-template.rst
- Skopiuj
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstdomytoolbox/doc/source/_templates/custom-class-template.rst
Hak do custom-module-template.rstznajduje się index.rstpowyżej, korzystając z :template:opcji. (Usuń ten wiersz, aby zobaczyć, co się dzieje przy użyciu domyślnych szablonów pakietów witryn).
custom-module-template.rst (dodatkowe linie zaznaczone po prawej stronie):
{{ 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 (dodatkowe linie zaznaczone po prawej stronie):
{{ 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 %}
lsdo pliku i jego edycja?