스핑크스의 자동화가 불충분하다

스핑크스의 자동화가 불충분하다

Python에서 5,000개 이상의 라인 프로젝트를 문서화하기 위해 Sphinx를 사용하려고 합니다.약 7개의 기본 모듈이 있습니다.제가 알기로는 autodoc을 사용하려면 프로젝트의 각 파일에 대해 다음과 같은 코드를 작성해야 합니다.

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

파일이 많아서 너무 지루해요.mods 패키지를 문서화하고 싶다고 명시할 수 있으면 훨씬 쉬워집니다.그런 다음 스핑크스는 패키지를 재귀적으로 통과하여 각 서브모듈의 페이지를 작성할 수 있습니다.

이런 기능이 있나요?그렇지 않으면 모든 .rst 파일을 만드는 스크립트를 작성할 수 있지만 시간이 많이 걸립니다.

제가 만든 대본을 확인하실 수 있습니다.도움이 될 것 같아요.

이 스크립트는 python 모듈 및 패키지를 찾는 디렉토리 트리를 해석하고 ReST 파일을 적절하게 생성하여 Sphinx로 코드 문서를 만듭니다.모듈 인덱스도 만듭니다.

갱신하다

이 스크립트는 이제 Sphinx 1.1의 apidoc의 일부가 되었습니다.

3.1 부터 스핑크스 【3.1 (2020년 6월)】sphinx.ext.autosummary!)는 자동.에는 자동 재귀가 있습니다.

따라서 자동 패키지 검출을 위해 모듈 이름을 하드코드로 만들거나 Sphinx AutoAPI 또는 Sphinx AutoPackageSummary와 같은 서드파티 라이브러리에 의존할 필요가 없습니다.

문서화할 Python 3.7 패키지의 예(Github 코드 및 Read The Docs 결과 참조):

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 new (새로 작성):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 %}

처음 질문을 받았을 때 스핑크스가 확장기능을 가지고 있었는지 알 수 없지만, 현재로선 사용하지 않고 그런 종류의 자동 생성 설정을 할 수 있습니다.sphinx-apidoc또는 유사한 스크립트입니다.아래는 내 프로젝트 중 하나에 적합한 설정입니다.

1. 가능하게 하다autosummary확장(및autodoc)의 경우conf.py파일링 및 설정autosummary_generate할 수 있는 선택권True커스텀을 사용하지 않는 경우 이 정도면 충분합니다.*.rst템플릿입니다.그렇지 않으면 템플릿 디렉토리를 제외 목록에 추가합니다.autosummary는, 그것들을 입력 파일로서 취급하려고 합니다(이것은 버그인 것 같습니다).

   extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
   autosummary_generate = True
   templates_path = [ '_templates' ]
   exclude_patterns = ['_build', '_templates']
   

2. 사용하다autosummary::TOC 트리에서index.rst이 예에서는 모듈용 매뉴얼에 대해 설명합니다.project.module1그리고.project.module2자동으로 생성되어 에 배치됩니다._autosummary디렉토리로 이동합니다.

   PROJECT
   =======
   
   .. toctree::
   
   .. autosummary::
      :toctree: _autosummary
   
      project.module1
      project.module2
   

3. 디폴트autosummary모듈 및 그 기능에 대한 매우 짧은 요약만 생성합니다.사용자 정의 템플릿 파일을 넣을 수 있는 내용을 변경하려면 다음과 같이 하십시오._templates/autosummary/module.rst(Jinja2와 함께 해석됩니다):

   {{ fullname }}
   {{ underline }}
   
   .. automodule:: {{ fullname }}
       :members:
   

결론부터 말하면,_autosummary디렉토리가 버전 관리 하에 있습니다.또한 원하는 이름을 지정하여 소스 트리의 임의의 위치에 배치할 수 있습니다(아래에 표시)._build동작하지 않습니다).

Sphinx AutoAPI는 바로 이 기능을 수행합니다.

각 패키지에서는__init__.py파일에는.. automodule:: package.module컴포넌트를 참조하십시오.

그럼 넌 할 수 있어.. automodule:: package대부분 원하는 걸 할 수 있어요

아마도 당신이 찾고 있는 것은 에피독과 이 스핑크스의 확장자일 것이다.

언급URL : https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough