이 문서에서,우리는 것을 통해 가고(매우)의 기초에서 문서를 생성하기 docstrings 에서는 파이썬 코드입니다. 그것은 약간의 갈기이지만,한 번 수행 한 후에는 모든 새로운 프로젝트에서 프로세스를 반복하는 것이 쉬울 것입니다.

우리의 목적을 위해,우리는 당신이(1)의 가치를 믿는 코드를 문서화하는 작업;(2)소원을 생성 문서에서 당신의 docstrings(3),사용하기로 선택한 스핑크스는 작업을 수행하기 위해.마지막으로 응용 프로그램에 대해 별개의 가상 환경을 이미 설정했다고 가정합니다. 관심있는 사람들을 위해 pyenv 환경 관리자를 정말 좋아합니다. 심지어 편리한 설치 프로그램이 있습니다.

pip를 통해 스핑크스를 설치해야합니다. 최소한 버전 1.3 이 필요하지만 좋은 이유가없는 한 가장 최신 버전을 설치해야합니다.

$ pip install sphinx

2 단계:설정 프로젝트를 빠른 시작

설치할 경우 스핑크스 패키지의 숫자를 명령 라인 유틸리티 설치뿐만 아니라.

그 중 하나,sphinx-quickstart이 빠르게 생성하는 기본 구성 파일과 디렉터리 구조에 대한 문서입니다.

프로젝트의 기본 디렉토리(즉,Git repo 루트)에서이 명령을 실행하십시오. 그것은 당신에게 그것이 행동이라고 결정할 여러 가지 질문을 할 것입니다. 할 수 있는 일반적으로 기본값을 수 있습니다,하지만 여기에 몇 가지 제안이의 경우 기본값:

후 프로그램이 실행,당신은 알 수 있는 새로운./docsconf.pyindex.rst,andMakefile.

3 단계:조정 conf.py 파일

기본conf.py파일 생성에 의해 빠른 유틸리티가 약 170 라인 길이,그래서 나는 포함되지 않습니다 모든 것은 여기에. 그러나 계속하기 전에 업데이트해야 할 몇 가지 항목이 있습니다.

말 스핑크스 위치의 당신의 Python 패키지

첫 번째 것은 우리가 할 필요가 있을 나타내는 파이썬 포함된 패키지는 귀하의 프로그램 코드와 관련하여conf.py파일입니다. 디렉토리 구조가 다음과 같이 보이는 경우:

당신을 표시해야한다는conf.py파일에는 스핑크스는 가야한다”up”하나 디렉토리 수준을 찾는 파이썬 패키지입니다.이것을 넣을 장소는 구성 파일의 첫 번째 섹션 끝에 있습니다. General Configuration설정 바로 앞에 다음과 같이 표시됩니다:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

지 않은 경우 주석으로,그것은 나타낼 것입니다 당신의 패키지에서와 같은 디렉토리conf.py파일입니다. 이렇게 변경해야합니다.

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Sphinx 확장 목록에”Napoleon”을 추가하여

Out of the box,Sphinx 는 전통적인 reStructuredText 로 작성된 docstrings 만 이해합니다. 는 경우가 있었음,권한의 작업으로 이러한 docstrings,당신은 알고 있는 그들은 고통을 작성하고 모든 인간의 친절을 읽을 때 그들을 보고 바로에서 소스 코드입니다.Numpy 와 Google:

나폴레옹 확장은 스핑크스는 다른 두 가지 인기있는 형식으로 작성된 docstrings 을 이해할 수 있습니다.

우리가해야 할 일은sphinx.ext.napoleonextensions목록에 추가하는 것입니다. 작업이 끝나면 다음과 같이해야합니다.

extensions = 

4 단계:인덱스 업데이트.rst

이 시점에서 실제로 빌드 프로세스를 실행하여 문서를 생성 할 수 있습니다. 그러나 그것은 꽤 실망 스러울 것입니다. 다음은 우리가 얻을 것입니다:

만큼 많이 나는 것 같은 스스로 가 우리의 docstrings 우리를 위해 그들을 준비 없이 잘 어떠한 구성,그것은 확실히 없다는 마법입니다.

앞으로 나아가려면 현재 다음과 같이 보이는index.rst파일에 약간의 수정을해야합니다:

여 시작할 수 없애는 주석의 정상에는 단지 소음:

,이제는 동안의 숫자가 있는 일을 우리가 할 수 있는 여기서 우리는 하려고 자신을 제한을 최소한 이 게시물을 적당한 길이 있습니다.

.. toctree::행이 보입니까? 그것이 스핑크스가 지시문이라고 부르는 것입니다. 스핑크스가 autodoc 확장을 사용하고자하는 코드 객체를 알 수 있도록index.rst파일에 autodoc 지시문을 추가해야합니다.

I’ll 가서를 추가 하나 나타내는 스핑크스는 그것을 문서화하는 공중의 구성원 내main.pymy_project패키지:

5 단계:쓰기 Docstrings

리지를 커버를 작성하는 방법 docstrings 에 Numpy 또는 구글에서 스타일이다.

그러나,여기에서 코드main.py포함하는 몇 가지 간단한 NumPy 스타일 docstrings 될 것입니다리 autodoc 지침:

6 단계: 당신의 문서를 생성!

이제 당신의 노동의 보상을 거둘 시간입니다. 에 있는지 확인./docsmake html

왔다면 다음을 따라 따라서 멀리,당신은 다음과 같은 내용이 표시될 것입니다.

만큼 당신이 볼 수는 영광스러운build succeeded메시지 끝에서, 당신이 갈 준비가 되어 보라 당신의 아름다운 창조물이다.

명령행에서 실행하는open _build/html/index.html(또는 열리는 페이지 귀하의 브라우저에서 수동으로)그리고 당신은 다음과 같은 내용이 표시될 것입니다:

다음 단계

우리는 단지 표면을 긁어 여기에있을 많이 사마귀에서 아직도 우리의 간단한 설명서입니다.

이 주제에 대한 다음 게시물에서는 autodoc 확장의 지시문을 더 깊이 파고 문서의 내용과 모양을 더 잘 제어 할 것입니다.