시작하기

Python 언어에는 방대한 문서가 있으며, 그중 상당 부분은 여러 작성자가 기여했습니다. Python 문서에 사용되는 마크업은 docutils 프로젝트가 개발하고 사용자 지정 디렉티브로 확장한 reStructuredText이며, HTML 출력을 후처리하는 데 Sphinx라는 도구 세트를 사용합니다.

HTML, PDF 또는 EPUB 형식의 문서는 reStructuredText 형식으로 작성되어 CPython Git 저장소에 포함된 텍스트 파일에서 생성됩니다.

참고

Python 문서에 기여하는 데 관심이 있더라도 원하지 않는다면 reStructuredText로 작성할 필요는 없으며, 일반 텍스트로 된 기여도 매우 환영합니다. docs@python.org로 이메일을 보내거나 추적기에 이슈를 등록하십시오.

소개

Python 문서는 오랫동안 무료 프로그래밍 언어의 문서로서는 훌륭하다고 평가받아 왔습니다. 여기에는 여러 이유가 있지만, 가장 중요한 이유는 Python의 창시자인 Guido van Rossum이 일찍부터 언어와 라이브러리의 문서 제공에 전념했다는 점과 사용자 커뮤니티가 문서 작성 및 유지 관리를 지속적으로 지원해 왔다는 점입니다.

커뮤니티의 참여는 문서 작성과 버그 보고부터 문서가 더 완전하거나 사용하기 쉬워질 수 있을 때의 단순한 불평에 이르기까지 다양한 형태로 이루어집니다.

이 절은 Python 문서의 작성자와 예비 작성자를 대상으로 합니다. 더 구체적으로는 표준 문서에 기여하거나 표준 문서와 동일한 도구를 사용하여 추가 문서를 개발하는 사람들을 위한 것입니다. 이 안내서는 Python 이외의 주제에 Python 문서 도구를 사용하는 작성자에게는 유용성이 떨어지며, 해당 도구를 전혀 사용하지 않는 작성자에게는 더욱 유용하지 않습니다.

Python 문서에 기여하고 싶지만 reStructuredText와 여기에 설명된 마크업 구조를 배울 시간이나 의향이 없더라도 Python 기여자들 사이에는 여러분을 환영하는 자리가 있습니다. 기존 문서를 더 명확하게 만들거나 누락된 문서를 제공할 수 있다고 생각할 때마다 기존 문서 팀은 여러분의 텍스트를 통합하기 위해 기꺼이 협력하며 마크업은 대신 처리합니다. 이 절의 내용 때문에 문서에 기여하고 싶은 마음을 포기하지 마십시오!

문서 빌드하기

문서를 빌드하려면 아래 절 중 하나의 단계를 따르십시오. HTML을 빌드한 후 웹 브라우저에서 Doc/build/html/index.html 파일을 열어 문서를 볼 수 있습니다.

초기 요구 사항

현재 작업 디렉터리가 복제한 CPython 저장소 내부의 최상위 Doc/ 디렉터리인지 확인하십시오. 다음 명령으로 해당 디렉터리로 이동할 수 있습니다:

cd Doc

Python 버전이 3.11 이상인지 확인하십시오. 다음 명령으로 확인할 수 있습니다:

python --version

가상 환경 만들기

필요한 종속성을 갖춘 새 venv 가상 환경을 다음과 같이 만들 수 있습니다:

make venv

관련 make로 문서를 빌드하면 이 환경을 직접 활성화하지 않아도 자동으로 사용합니다.

새 가상 환경을 수동으로 생성하십시오. 문서를 빌드하기 전에 항상 이 환경을 활성화하십시오.

make / make.bat을 사용하여 빌드하기

유닉스용 Makefile(Doc/Makefile)이 제공됩니다.

윈도우용 make.bat(Doc/make.bat)이 제공되며, 유닉스 Makefile을 현실적으로 가능한 한 가깝게 모방합니다.

중요

Windows make.bat 배치 파일에는 make venv 타깃이 없습니다. 대신 누락된 종속성을 현재 활성화된 환경에 자동으로 설치합니다(활성화된 환경이 없으면 기본 Python에 설치합니다). make.bat을 실행하기 전에 위에서 생성한 환경이 활성화되어 있는지 확인하십시오.

문서를 HTML로 빌드하려면 다음을 실행하십시오:

make html

.\make html

팁

  • 웹 브라우저에서 문서를 열려면 html을 htmlview로 바꾸십시오 빌드 완료 후 열립니다.

  • 문서를 다시 빌드하고 로컬 서버를 시작하며 reST 파일을 변경할 때 브라우저에서 페이지를 자동으로 새로 고치려면 html을 htmllive로 바꾸십시오(Unix 전용).

  • 문서 번역을 빌드하려면 이 가이드를 참조하십시오.

빌드 과정에서 시간을 절약하기 위해 문서의 특정 페이지만 빌드할 수도 있습니다. 다음은 두 페이지를 빌드하는 예입니다:

make html SOURCES="tutorial/classes.rst tutorial/inputoutput.rst"

관련 Sphinx를 직접 사용하여 빌드하기을 참조하십시오. sphinx-build를 호출할 때 다음과 같이 원하는 페이지를 마지막 매개변수로 전달하십시오:

python -m sphinx -b html . build/html tutorial/classes.rst tutorial/inputoutput.rst

Sphinx Lint로 문서의 일반적인 오류를 검사하려면(모든 풀 리퀘스트에서 실행됩니다) 다음을 사용하십시오:

make check

.\make check

관련 make에서 지원하는 다른 대상을 나열하려면 다음을 실행하십시오:

make help

.\make help

자세한 내용은 Doc/README.rst을 참조하십시오.

Sphinx를 직접 사용하여 빌드하기

고급 사용자는 특수한 옵션을 전달하거나 특정 사용 사례를 처리하기 위해 Sphinx를 직접 호출할 수 있습니다.

위에서 생성한 환경이 활성화되어 있는지 확인하십시오. 그런 다음 문서 요구 사항인 Doc/requirements.txt을 설치하십시오. pip 사용하기:

python -m pip install --upgrade -r requirements.txt

마지막으로 다음과 같이 Sphinx를 직접 호출하십시오.:

python -m sphinx -b html . build/html

다른 Sphinx builder를 사용하려면 위의 html을 원하는 빌더 name으로 바꾸십시오.