Nice programing

doxygen을 사용하여 Python 코드를 문서화하는 방법

nicepro 2020. 10. 4. 13:25
반응형

doxygen을 사용하여 Python 코드를 문서화하는 방법 [닫힌]


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_JAVAYES.

솔직히 그 차이에 약간 놀랐습니다. doxygen이 ## 블록 또는 "" "블록에서 주석을 감지하면 대부분의 작업이 완료되고 다음에서 특수 명령을 사용할 수있는 것 같습니다. 아마도 그들은 "" "를 사용하는 사람들이 더 많은 파이썬 문서화 관행을 고수하고 특별한 doxygen 명령을 방해 할 것이라고 기대할까요?


doxypy의 입력 필터는 표준 파이썬 문서화 문자열 형식으로 거의 모든 Doxygen을의 서식 태그를 사용할 수 있습니다. 나는 그것을 사용하여 대규모 혼합 C ++ 및 Python 게임 응용 프로그램 프레임 워크를 문서화하며 잘 작동합니다.


Sphinx는 주로 소스 코드와 독립적으로 작성된 문서의 형식을 지정하는 도구입니다.

Python 독 스트링 에서 API 문서를 생성하기위한 주요 도구는 pdocpydoctor 입니다. 다음은 TwistedBazaar에 대해 pydoctor가 생성 한 API 문서입니다 .

물론 작업하는 동안 독 스트링 만보싶다면 " pydoc "명령 줄 도구와 help()대화 형 인터프리터에서 사용할 수 있는 기능이 있습니다.


결국 두 가지 옵션 만 있습니다.

Doxygen을 사용하여 콘텐츠를 생성하거나 Sphinx *를 사용하여 콘텐츠를 생성합니다.

  1. Doxygen : 대부분의 Python 프로젝트에서 선택하는 도구가 아닙니다. 그러나 C 또는 C ++로 작성된 다른 관련 프로젝트를 처리해야하는 경우 이해가 될 수 있습니다. 이를 위해 doxypypy를 사용하여 Doxygen과 Python 간의 통합을 개선 할 수 있습니다 .

  2. Sphinx : Python 프로젝트를 문서화하기위한 사실상의 도구입니다. 여기에는 수동, 반자동 (스텁 생성) 및 완전 자동 (Doxygen 유사)의 세 가지 옵션이 있습니다.

    1. For manual API documentation you have Sphinx autodoc. This is great to write a user guide with embedded API generated elements.
    2. For semi-automatic you have Sphinx autosummary. You can either setup your build system to call sphinx-autogen or setup your Sphinx with the autosummary_generate config. You will require to setup a page with the autosummaries, and then manually edit the pages. You have options, but my experience with this approach is that it requires way too much configuration, and at the end even after creating new templates, I found bugs and the impossibility to determine exactly what was exposed as public API and what not. My opinion is this tool is good for stub generation that will require manual editing, and nothing more. Is like a shortcut to end up in manual.
    3. Fully automatic. This have been criticized many times and for long we didn't have a good fully automatic Python API generator integrated with Sphinx until AutoAPI came, which is a new kid in the block. This is by far the best for automatic API generation in Python (note: shameless self-promotion).

There are other options to note:

  • Breathe: this started as a very good idea, and makes sense when you work with several related project in other languages that use Doxygen. The idea is to use Doxygen XML output and feed it to Sphinx to generate your API. So, you can keep all the goodness of Doxygen and unify the documentation system in Sphinx. Awesome in theory. Now, in practice, the last time I checked the project wasn't ready for production.
  • pydoctor*: Very particular. Generates its own output. It has some basic integration with Sphinx, and some nice features.

An other very good documentation tool is sphinx. It will be used for the upcoming python 2.6 documentation and is used by django and a lot of other python projects.

From the sphinx website:

  • Output formats: HTML (including Windows HTML Help) and LaTeX, for printable PDF versions
  • Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information
  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
  • Automatic indices: general index as well as a module index
  • Code handling: automatic highlighting using the Pygments highlighter
  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules, and more

참고URL : https://stackoverflow.com/questions/58622/how-to-document-python-code-with-doxygen

반응형