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

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

---

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

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

파일이 많기 때문에 너무 지루합니다. 'mods'패키지를 문서화하도록 지정하면 훨씬 쉬울 것입니다. 그러면 스핑크스는 재귀 적으로 패키지를 살펴보고 각 하위 모듈에 대한 페이지를 만들 수 있습니다.

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

---

내가 만든 이 스크립트 를 확인할 수 있습니다 . 나는 그것이 당신을 도울 수 있다고 생각합니다.

이 스크립트는 파이썬 모듈 및 패키지를 찾는 디렉토리 트리를 구문 분석하고 Sphinx로 코드 문서를 작성하기 위해 ReST 파일을 적절하게 작성합니다. 또한 모듈 색인을 작성합니다.

최신 정보

이 스크립트는 이제 apidoc 로 Sphinx 1.1의 일부입니다 .

---

autosummary원래 질문을 받았을 때 Sphinx가 확장 기능을 사용 했는지 여부는 알 수 없지만 현재는 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::목차 트리에서 사용하십시오 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해도 작동하지 않음).

---

각 패키지에서 __init__.py파일 .. automodule:: package.module에는 패키지의 각 부분에 대한 구성 요소 가있을 수 있습니다 .

그렇다면 당신은 할 수 .. automodule:: package있고 대부분 원하는 것을합니다.

---

아마 당신이 찾고있는 것은 Epydoc 및이 Sphinx extension 입니다.

---

스핑크스 AutoAPI 는 정확하게 이것을 수행합니다.

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