시작하기

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으로 빌드하기

Unix Makefile인 Doc/Makefile이 제공됩니다.

Windows make.bat인 Doc/make.bat이 제공되며, 이는 Unix Makefile을 실용적인 범위에서 최대한 가깝게 흉내 내려고 합니다.

중요

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

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

make html

.\make html

팁

  • html을 htmlview로 바꾸면 웹 브라우저에서 문서가 열립니다. 문서는 빌드가 완료된 후에 열립니다.

  • html을 htmllive로 바꾸면 문서를 다시 빌드하고, 로컬 서버를 시작하며, reST 파일을 변경할 때 브라우저에서 페이지를 자동으로 다시 불러옵니다(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로 문서의 흔한 오류를 검사하려면(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으로 바꾸십시오.