C 또는 PHP 코드 문서를 작성하는 Doxygen을 좋아합니다. 다가오는 Python 프로젝트가 있는데 Python에는 /* .. */주석 이없고 자체 문서화 기능이있어 문서화하는 비단뱀 방식 인 것처럼 보입니다.
Doxygen에 익숙한데이를 사용하여 Python 문서를 생성하려면 어떻게해야합니까? 특별히 알아야 할 사항이 있습니까?
답변:
이것은 doxygen 웹 사이트에 문서화되어 있지만 여기에 요약하면 다음과 같습니다.
doxygen을 사용하여 Python 코드를 문서화 할 수 있습니다. Python 문서 문자열 구문을 사용할 수 있습니다.
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
이 경우 주석은 doxygen에 의해 추출되지만 특수한 doxygen 명령 을 사용할 수 없습니다 .
또는 (doxygen의 C 스타일 언어와 유사 #) 멤버 앞의 첫 번째 줄에있는 주석 표시 자 ( )를 두 배로 늘릴 수 있습니다 .
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
이 경우 특수 doxygen 명령을 사용할 수 있습니다. 이 특별한 파이썬 출력 모드는 없습니다,하지만 당신은 분명히 설정하여 결과를 향상시킬 수 있습니다 OPTMIZE_OUTPUT_JAVA로 YES.
솔직히 그 차이에 약간 놀랐습니다. doxygen이 ## 블록 또는 "" "블록에서 주석을 감지하면 대부분의 작업이 완료되고 다음에서 특수 명령을 사용할 수 있습니다. 아마도 그들은 "" "를 사용하는 사람들이 더 많은 파이썬 문서화 관행을 고수하고 특별한 doxygen 명령을 방해 할 것이라고 기대할까요?
doxypy의 입력 필터는 표준 파이썬 문서화 문자열 형식으로 거의 모든 Doxygen을의 서식 태그를 사용할 수 있습니다. 나는 그것을 사용하여 대규모 혼합 C ++ 및 Python 게임 응용 프로그램 프레임 워크를 문서화하며 잘 작동합니다.
결국 두 가지 옵션 만 있습니다.
Doxygen을 사용하여 콘텐츠를 생성하거나 Sphinx *를 사용하여 콘텐츠를 생성합니다.
Doxygen : 대부분의 Python 프로젝트에서 선택하는 도구가 아닙니다. 그러나 C 또는 C ++로 작성된 다른 관련 프로젝트를 처리해야한다면 이치에 맞을 수 있습니다. 이를 위해 doxypypy를 사용하여 Doxygen과 Python 간의 통합을 개선 할 수 있습니다 .
Sphinx : Python 프로젝트를 문서화하기위한 사실상의 도구입니다. 여기에는 수동, 반자동 (스텁 생성) 및 완전 자동 (Doxygen 유사)의 세 가지 옵션이 있습니다.
autosummary_generate. 자동 요약이있는 페이지를 설정 한 다음 페이지를 수동으로 편집해야합니다. 옵션이 있지만이 접근 방식에 대한 제 경험은 너무 많은 구성이 필요하다는 것입니다. 그리고 결국에는 새 템플릿을 만든 후에도 버그가 발견되었고 공개 API로 노출 된 항목과 그렇지 않은 항목을 정확하게 결정할 수 없었습니다. 제 생각에는이 도구는 수동 편집이 필요한 스텁 생성에 적합하며 그 이상은 없습니다. 수동으로 끝나는 지름길과 같습니다.참고할 다른 옵션이 있습니다.
__all__.
다른 아주 좋은 문서화 도구는 스핑크스 입니다. 그것은 곧 파이썬 2.6에 사용되는 문서 에 의해 사용되는 장고 와 다른 파이썬 프로젝트의 많은.
스핑크스 웹 사이트에서 :