건축 문서¶
BeeWare'의 문서에 변경 사항을 적용하기 전에 기존 문서를 빌드할 수 있는지 확인하는 것이 좋습니다.
문서를 작성하기 전에, 개발 환경을 설정해 두십시오.
Python 3.13 인터프리터가 설치되어 있고 경로에 접근 가능해야 합니다(즉, python3.13 명령어가 Python 3.13 인터프리터를 실행해야 함).
BeeWare는 문서 생성에 tox를 사용합니다. 다음 tox 명령어는 프로젝트 루트 디렉토리에 위치한
tox.ini 파일과 동일한 위치에서 실행해야 합니다.
라이브 문서 미리보기¶
문서 편집을 신속하게 지원하기 위해 BeeWare에는 "실시간 미리보기" 모드가 있습니다.
라이브 미리보기는 경고와 함께 빌드됩니다!
라이브 서버는 문서 업데이트를 반복 작업하는 데 사용할 수 있습니다. 업데이트 과정에서 마크업 문제가 발생할 수 있습니다. WARNING로
표시된 문제는 표준 빌드를 실패하게 하지만, 라이브 서버는 콘솔 출력에 경고를 표시하면서 빌드를 계속하도록 설정되어 있습니다. 이를 통해 라이브
미리보기를 재시작하지 않고도 반복 작업을 수행할 수 있습니다.
WARNING는 ERROR와 다릅니다. ERROR로 간주되는 문제를 도입하면 라이브 서버가 실패하고 재시작이 필요합니다.
WARNING 문제가 해결될 때까지 다시 시작되지 않습니다.
라이브 서버를 시작하려면:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
이 명령은 문서를 빌드하고, 문서를 제공하기 위해 웹 서버를 시작하며, 문서 소스 파일에 대한 변경 사항을 감시합니다.
서버가 시작되면 콘솔 출력에 다음과 같은 내용이 표시됩니다:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
브라우저를 열고 제공된 URL로 이동하세요. 이제 문서 작업을 반복할 수 있습니다. 변경 사항이 감지되면 문서가 재구축되며, 수정된 페이지를 보고 있는 모든 브라우저가 자동으로 새로 고쳐집니다.
docs-live는 초기 단계입니다
docs-live을 실행하여 라이브 서버와 작업하는 것은 초기 반복 작업을 위한 것입니다. 풀 리퀘스트를 제출하기 전에 항상 로컬 빌드를
실행해야 합니다.
로컬 빌드¶
반복 작업을 완료한 후에는 문서의 로컬 빌드를 수행해야 합니다. 이 빌드 프로세스는 마크업 문제가 있을 경우 실패하도록 설계되었습니다. 이를 통해 라이브 서버에서는 놓쳤을 수 있는 모든 문제를 포착할 수 있습니다.
로컬 빌드 생성¶
로컬 빌드를 생성하려면:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
이 빌드의 출력은 프로젝트 루트 디렉토리의 _build 디렉토리에 생성됩니다.
로컬 번역 빌드 생성¶
BeeWare's 문서가 여러 언어로 번역됩니다. 영어 문서의 업데이트는 다른 언어 빌드에서 문제를 일으킬 수 있습니다. 풀 리퀘스트를 제출하기 전에 모든 빌드가 정상 작동하는지 확인하는 것이 중요합니다.
사용 가능한 모든 번역에 대한 빌드를 생성하려면:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
각 언어 빌드의 결과물은 해당 _build/html/<languagecode> 디렉터리에 저장됩니다. 여기서 <languagecode>는
특정 언어에 할당된 2자리 또는 5자리 언어 코드입니다(예: 프랑스어는 fr, 이탈리아어는 it 등).
단일 빌드에서 문제를 발견한 경우, tox -e docs-<languagecode>를 실행하여 해당 개별 빌드를 따로 실행할 수 있습니다.
예를 들어, 프랑스어 문서만 빌드하려면 다음을 실행하세요:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
단일 언어 빌드의 출력은 _build 디렉터리에 생성됩니다.
문서 린팅¶
빌드 프로세스는 마크다운 문제를 식별하지만, BeeWare는 스타일과 서식을 위한 추가 검사를 수행하며 이를 "린팅"이라고 합니다. 린팅 검사를 실행하려면:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
이것은 문서에 다음이 포함되어 있지 않음을 검증합니다:
- 깨진 하이퍼링크
- 맞춤법이 틀린 단어
단어의 올바른 철자가 오타로 식별되면 해당 단어를 docs/spelling_wordlist 안에 있는 목록에 추가하십시오. 이렇게 하면 해당
단어가 맞춤법 검사기 사전에 추가됩니다. 이 목록에 추가할 때 다음 사항을 기억하십시오:
- 미국식 철자를 선호하며, 프로그래밍 특유의 관용적 표현(예: "apps")과 명사의 동사화(예: "scrollable")에 대해서는 일부 유연성을 허용합니다.
- 제품명에 대한 모든 언급은 해당 제품의 권장 대소문자 표기법을 사용해야 합니다. (예: "macOS", "GTK", "pytest", "Pygame", "PyScript").
- 어떤 용어가 "암호"로 사용되고 있다면, 사전(dictionary)에 추가하기보다는 리터럴(
like this)로 인용해야 합니다.
문서 생성을 성공적으로 완료하면, 이제 문서 작성을 시작할 준비가 된 것입니다.