pydoc — 문서 생성기와 온라인 도움말 시스템

소스 코드: Lib/pydoc.py

pydoc 모듈은 Python 모듈에서 자동으로 문서를 생성해요. 문서는 콘솔에 텍스트 페이지로 표시되거나, 웹 브라우저로 제공되거나, HTML 파일로 저장될 수 있어요.

모듈, 클래스, 함수, 메서드에 대해 표시되는 문서는 그 객체의 docstring(즉, __doc__ 속성)과, 재귀적으로 문서화 가능한 그 멤버들의 docstring에서 파생돼요. docstring이 없으면 pydoc은 소스 파일에서 클래스·함수·메서드 정의 바로 위의 주석 줄 블록, 또는 모듈 맨 위에서 설명을 얻으려고 시도해요(inspect.getcomments() 참고).

내장 함수 help()는 대화형 인터프리터에서 온라인 도움말 시스템을 호출하며, 그 시스템은 pydoc을 사용해 문서를 콘솔에 텍스트로 생성해요. 같은 텍스트 문서는 운영 체제의 명령 프롬프트에서 pydoc을 스크립트로 실행해 Python 인터프리터 밖에서도 볼 수 있어요. 예를 들어 셸 프롬프트에서

python -m pydoc sys

를 실행하면 Unix의 man 명령이 보여 주는 매뉴얼 페이지와 비슷한 스타일로 sys 모듈에 대한 문서가 표시돼요. pydoc의 인자는 함수, 모듈, 패키지의 이름이거나, 모듈이나 패키지 안의 클래스, 메서드, 함수를 가리키는 점 표기(dotted reference)일 수 있어요. pydoc의 인자가 경로처럼 보이고(즉, Unix에서 슬래시 같은 운영 체제의 경로 구분자를 포함) 기존 Python 소스 파일을 가리키면, 그 파일에 대한 문서가 생성돼요.

참고 — 객체와 그 문서를 찾기 위해 pydoc은 문서화할 모듈을 임포트해요. 따라서 모듈 수준의 코드가 그 시점에 실행돼요. if __name__ == '__main__': 가드를 사용해 파일이 임포트될 때가 아니라 스크립트로 호출될 때만 코드가 실행되게 하세요.

콘솔에 출력을 인쇄할 때 pydoc은 더 쉽게 읽기 위해 출력을 페이지 단위로 나누려고 시도해요. MANPAGER나 PAGER 환경 변수 중 하나가 설정되어 있으면 pydoc은 그 값을 페이지 나눔 프로그램으로 사용해요. 둘 다 설정되어 있으면 MANPAGER가 사용돼요.

인자 앞에 -w 플래그를 지정하면 콘솔에 텍스트를 표시하는 대신 현재 디렉터리의 파일에 HTML 문서를 써요.

인자 앞에 -k 플래그를 지정하면 인자로 주어진 키워드를 모든 사용 가능한 모듈의 synopsis 줄에서 검색해요. 다시 말해 Unix man 명령과 비슷한 방식이에요. 모듈의 synopsis 줄은 그 문서 문자열의 첫 줄이에요.

pydoc을 사용해 방문하는 웹 브라우저에 문서를 제공할 로컬 머신의 HTTP 서버를 시작할 수도 있어요. python -m pydoc -p 1234는 포트 1234에서 HTTP 서버를 시작해, 여러분이 선호하는 웹 브라우저에서 http://localhost:1234/의 문서를 탐색할 수 있게 해 줘요. 포트 번호로 0을 지정하면 임의의 사용되지 않은 포트가 선택돼요.

경고 — pydoc HTTP 서버는 개발 중 로컬 사용을 위한 것이며 프로덕션 사용에는 적합하지 않아요.

**python -m pydoc -n **은 주어진 호스트 이름에서 수신하는 서버를 시작해요. 기본적으로 호스트 이름은 'localhost'지만 서버를 다른 머신에서도 도달하려면 응답할 호스트 이름을 바꾸고 싶을 수 있어요. 개발 중에 컨테이너 안에서 pydoc을 실행하려 할 때 특히 유용해요.

python -m pydoc -b는 서버를 시작하고 추가로 웹 브라우저를 모듈 인덱스 페이지로 열어요. 제공되는 각 페이지 맨 위에는 탐색 표시줄이 있는데, 거기서 개별 항목에 대한 도움말을 Get 하거나, 그 synopsis 줄에 키워드가 있는 모든 모듈을 Search 하고, Module index·Topics·Keywords 페이지로 이동할 수 있어요.

pydoc이 문서를 생성할 때 현재 환경과 경로를 사용해 모듈을 찾아요. 따라서 pydoc spam을 호출하면 정확히 Python 인터프리터를 시작해 import spam을 입력했을 때 얻을 버전의 모듈을 문서화해요.

핵심 모듈의 모듈 문서는 https://docs.python.org/X.Y/library/에 있는 것으로 가정되며, 여기서 X와 Y는 Python 인터프리터의 major-minor 버전 번호예요. 이는 PYTHONDOCS 환경 변수를 다른 URL이나 Library Reference Manual 페이지를 포함한 로컬 디렉터리로 설정해 덮어쓸 수 있어요.

버전 3.2에서 변경: -b 옵션 추가.

버전 3.3에서 변경: -g 명령줄 옵션 제거.

버전 3.4에서 변경: pydoc은 이제 callable에서 시그니처 정보를 추출할 때 inspect.getfullargspec() 대신 inspect.signature()를 사용함.

버전 3.7에서 변경: -n 옵션 추가.

출처: Python 표준 라이브러리

본문

더 알아보기

py_compile — 소스 파일을 바이트코드 파일로 컴파일.
compileall — 디렉터리 트리의 모든 소스를 바이트-컴파일하는 유틸리티.