Từ Sphinx phiên bản 3.1 (tháng 6 năm 2020), sphinx.ext.autosummary(cuối cùng!) Đã được đệ quy.
Vì vậy, không cần phải cứng tên mô-đun hoặc dựa vào các thư viện bên thứ 3 như Sphinx AutoAPI hoặc Sphinx AutoPackageSummary để phát hiện gói tự động của họ nữa.
Ví dụ gói Python 3.7 vào tài liệu ( xem mã trên Github và kết quả trên 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(lưu ý :recursive:tùy chọn mới ):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
Điều này là đủ để tự động tóm tắt mọi mô-đun trong gói, tuy nhiên được lồng sâu. Đối với mỗi mô-đun, sau đó nó tóm tắt mọi thuộc tính, chức năng, lớp và ngoại lệ trong mô-đun đó.
Mặc dù, điều kỳ lạ là các sphinx.ext.autosummarymẫu mặc định không tiếp tục tạo các trang tài liệu riêng cho từng thuộc tính, chức năng, lớp và ngoại lệ và liên kết với chúng từ các bảng tóm tắt. Có thể mở rộng các mẫu để làm điều này, như được hiển thị bên dưới, nhưng tôi không thể hiểu tại sao đây không phải là hành vi mặc định - chắc chắn đó là điều mà hầu hết mọi người sẽ muốn ..? Tôi đã nêu nó như một yêu cầu tính năng .
Tôi đã phải sao chép các mẫu mặc định cục bộ và sau đó thêm chúng vào:
- Sao chép
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstvàomytoolbox/doc/source/_templates/custom-module-template.rst
- Sao chép
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstvàomytoolbox/doc/source/_templates/custom-class-template.rst
Móc vào custom-module-template.rstlà ở index.rsttrên, sử dụng :template:tùy chọn. (Xóa dòng đó để xem điều gì xảy ra bằng cách sử dụng các mẫu gói trang mặc định.)
custom-module-template.rst (dòng bổ sung ghi chú bên phải):
{{ 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 (dòng bổ sung ghi chú bên phải):
{{ 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đến một tập tin và chỉnh sửa đó?