स्फिंक्स संस्करण 3.1 (जून 2020) से, sphinx.ext.autosummary (अंत में!) में पुनरावृत्ति होती है।
तो हार्ड कोड मॉड्यूल नामों की जरूरत नहीं है या Sphinx AutoAPI या Sphinx AutoPackageSummary जैसी 3 पार्टी लाइब्रेरी पर निर्भर हैं अपने स्वचालित पैकेज का पता लगाने के लिए ।
उदाहरण के लिए पाइथन 3.7 पैकेज टू डॉक्यूमेंट ( जीथब पर कोड देखें और 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फ़ाइल को रूट करना और उसे संपादित करना कितना कठिन हो सकता है?