는 방법을 문서 Python 물 과학과 같은 다른 분야에 대한[마감]

StackOverflow https://stackoverflow.com/questions/58622

문제

나는 다음과 같물 과학과 같은 다른 분야에 대해 설명서를 만들의 C 나 PHP 의 코드입니다.내가 곧 파이썬 프로젝트 및 생각을 기억하는 파이썬 없 /* .. */ 의견이 있고,또한 그것의 자신의 자기-문서 서비스를 제공할 수 있을 것 같 pythonic 방법을 문서화합니다.

이후 나는 익숙해물 과학과 같은 다른 분야에 대한 방법을 사용할 수 있습니 그것을 생산하는 내 Python 서류가 있습니까?거기에 아무것도 특정 필요를 알고 있는가?

도움이 되었습니까?

해결책

이 문서화합물 과학과 같은 다른 분야에 대한 웹사이트, 하지만,요약 여기:

당신이 사용할 수 있습물 과학과 같은 다른 분야에 대하여 문서화하는 파이썬 코드입니다.하게 사용할 수 있는 파이썬 설명서 문자열 syntax:

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

어떤 경우에는 의견을 추출물 과학과 같은 다른 분야에 대한,하지만 당신은 할 수 없 사용 특별물 과학과 같은 다른 분야에 대한 명령.

나 당신은 할 수 있습니다(유 C-style 언어서물 과학과 같은 다른 분야에 대한)두 배로 주석 마커(#)첫 번째 줄에 전원:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

는 경우에,당신은 특별한 사용할 수 있습니다물 과학과 같은 다른 분야에 대한 명령입니다.이 없는 특정 Python 출력 모드,하지만 당신은 분명히 결과를 향상시킬에 의해 설정 OPTMIZE_OUTPUT_JAVA 하기 YES.

솔직히,나는 약간의 놀라게에 차이를 보인다면 다음과 같물 과학과 같은 다른 분야에 대한 감지할 수 있습니다 의견에##블록 또는"""블록,대부분의 작업이 될 수행하고 당신이 사용할 수 있는 특수 명령을 어느 경우에.어쩌면 그들은 기대를 사용하는 사람들"""을 준수하는 더 Pythonic 문서 관행을 방해하는 특별물 과학과 같은 다른 분야에 대한 명령?

다른 팁

이 doxypy 입력 필터를 사용할 수 있습 거의 모든물 과학과 같은 다른 분야에 대한의 형식 태그를 표준 Python docstring 형식입니다.나는 그것을 사용하여 문서 큰 혼합 C++및 파이썬 게임 프로그램,그리고 잘 작동됩니다.

스핑크스는 주로 위한 도구를 포맷 문서 독립적으로 작성된 소스 코드에서,내가 그것을 이해합니다.

를 생성하기 위한 API 문서에서는 파이썬 docstrings,주요 툴 pdoc 고 pydoctor.여기에 pydoctor 생성되 API 문서 트위스트 고 시장.

물론,하려는 경우에는 보 docstrings 작업하는 동안에 물건을 거기"pydoc"명령행 도구뿐만 아니라 help() 함수에서 사용할 수 있는 대화형 인터프리터입니다.

결국,당신은 단지 두 가지 옵션을 사용할 수 있습니다.

당신을 생성합을 사용하여 내용물 과학과 같은 다른 분야에 대한,또는 당신을 생성하는 컨텐츠 사용하는 스핑크스*.

  1. 물 과학과 같은 다른 분야에 대:그것은 도구에 대한 선택의 대부분의 프로젝트 파이썬.하지만 경우에 당신은 거의 다른 관련된 프로젝트 C 또는 C++로 작성할 수 있습니다.이를 위해 당신을 향상시킬 수 있습 통합물 과학과 같은 다른 분야에 대한 사과를 사용하기 doxypypy.

  2. Sphinx:사실상의 도구에 대한 문서화하는 프로젝트 파이썬.당신은 세 가지 옵션이 여기:수동,자동(stub 세대)에 완전히 자동적인(물 과학과 같은 다른 분야에 대한 다음과 같).

    1. 동 API 설명서 당신은 스스 autodoc.이를 쓰기 사용자 안내가 포함된 API 를 생성 요소입니다.
    2. 반자동을 스스 autosummary.할 수 있습 설정 빌드 시스템 호출하는 스핑크스-autogen 또는 설정의 스핑크스와 autosummary_generate config.당신이 필요로 설정 페이지로 autosummaries,그리고 다음을 수동으로 편집 페이지입니다.당신은 옵션이 있지만,제 경험으로 접근 방식이 필요하다는 것이다 너무 많은 구성,그리고 최종 후에도 새로 만드는 템플릿에,나는 버그를 발견하고 불가능을 정확하게 결정에 노출되었으로 공개 API 것이 아닙니다.내 의견은 이 도구에 대 한 좋은 스텁 생성해야 하는 수동으로 편집,그리고 아무것도 없습니다.은 다음과 같 바로 가기를 끝에 매뉴얼입니다.
    3. 완전히 자동적입니다.이 비판되는 많은 시간과 장 우리가 좋은 완전히 자동적인 파이썬 API 발전기 통합된 스핑크스까지 AutoAPI 왔는 새로운 아이에 차단합니다.이것은 최고의 자동 API 세대에서는 파이썬(참고:뻔뻔한 자기진).

다른 옵션을 참고:

  • 호흡:이를 시작으로 매우 좋은 아이디어,그리고 말할 때 당신과 함께 주도적인 역할을 수행하는 관련 프로젝트에는 다른 언어를 사용물 과학과 같은 다른 분야에 대한.아이디어가 사용하물 과학과 같은 다른 분야에 대한 XML 을 출력하고 그것을 먹는 스핑크스를 생성하는 API 입니다.그래서,당신은 당신을 유지할 수 있습의 모든 선물 과학과 같은 다른 분야에 대한 통합 문서 시스템에서는 스핑크스.에서 멋진 이론이다.이제 실제로 지난번 프로젝트에 대한 준비가되어 있지 않았 생산입니다.
  • pydoctor*:아주 특별합니다.성 자체적으로 출력됩니다.그것은 몇 가지 기본적인 통합된 스핑크스,그리고 몇 가지 좋은 기능입니다.

는 다른 매우 좋은 문서 도구 sphinx.사용될 것이 곧 python2.6 문서 에 의해 사용된 django 그리고 다른 많은 프로젝트 파이썬.

에서 스핑크스 웹 사이트:

  • 출력 형식:HTML(Windows HTML 도움말고),라텍스를 위한 printable PDF 버전
  • 다양한 크로스를 참조:semantic markup 및 자동 연결 기능,클래스,용어와 유사한 조각의 정보
  • 계층 구조:쉽게 정의의 문서 나무,자동 연결하는 형제 자매들,부모님과 어린이
  • 자동 인덱스:일반 인덱스뿐만 아니라 모듈 index
  • 코드 처리:동 강조를 사용하 Pygments 하이라이트
  • 장:자동적인 테스트의 코드를 포함 docstrings Python 에서 모듈 및상
라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top