จาก Sphinx เวอร์ชั่น 3.1 (มิถุนายน 2020), sphinx.ext.autosummary(ในที่สุด!) ได้เรียกซ้ำ
ดังนั้นไม่จำเป็นต้องใช้ชื่อโมดูลรหัสฮาร์ดหรือพึ่งพาไลบรารีบุคคลที่สามเช่นSphinx AutoAPIหรือSphinx AutoPackageS บทสรุปสำหรับการตรวจสอบแพ็คเกจอัตโนมัติของพวกเขาอีกต่อไป
ตัวอย่างแพ็คเกจ 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ไปยังไฟล์นั้นทำได้ยากเพียงใด