[python] 스핑크스 오토 독은 충분히 자동적이지 않다

스핑크스 버전 3.1 (2020 년 6 월)부터 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 %}

---

답변