pydoc — 문서 생성기 및 온라인 도움말 시스템
pydoc — 문서 생성기 및 온라인 도움말 시스템
pydoc 모듈은 파이썬 모듈에서 자동으로 문서를 생성해요. 문서는 콘솔의 텍스트 페이지로 표시되거나, 웹 브라우저에 제공되거나, HTML 파일로 저장될 수 있어요.
본문
모듈·클래스·함수·메서드에 대해 표시되는 문서는 객체의 docstring(즉 __doc__ 속성)과, 재귀적으로 그 문서화 가능한 멤버들에서 파생돼요. docstring 이 없으면 pydoc 은 소스 파일에서 클래스·함수·메서드 정의 바로 위의 주석 줄 블록이나 모듈 맨 위에서 설명을 얻으려 해요(inspect.getcomments() 참고).
내장 함수 help() 는 대화형 인터프리터에서 온라인 도움말 시스템을 호출하는데, 이는 pydoc 을 사용해 문서를 콘솔 텍스트로 생성해요. 같은 텍스트 문서는 운영체제의 커맨드 프롬프트에서 pydoc 을 스크립트로 실행해 파이썬 인터프리터 밖에서도 볼 수 있어요. 예를 들어 셸 프롬프트에서
python -m pydoc sys
를 실행하면 Unix 의 man 명령이 보여주는 매뉴얼 페이지와 비슷한 스타일로 sys 모듈에 대한 문서를 표시해요. pydoc 의 인자는 함수·모듈·패키지 이름이거나, 모듈·패키지 안의 클래스·메서드·함수에 대한 점 표기 참조일 수 있어요. 인자가 경로처럼 보이고(즉 운영체제의 경로 구분자를 포함) 기존 파이썬 소스 파일을 가리키면 그 파일에 대한 문서가 생성돼요.
참고: 객체와 그 문서를 찾기 위해 pydoc 은 문서화할 모듈을 import 해요. 따라서 모듈 레벨의 어떤 코드도 그 순간 실행돼요. 파일이 스크립트로 호출될 때만 코드를 실행하고 import 될 때는 실행하지 않으려면 if __name__ == '__main__': 가드를 사용하세요.
콘솔에 출력할 때 pydoc 은 더 쉽게 읽도록 출력을 페이지화하려 해요. MANPAGER 또는 PAGER 환경 변수가 설정돼 있으면 pydoc 이 그 값을 페이지화 프로그램으로 사용해요. 둘 다 설정돼 있으면 MANPAGER 를 사용해요.
인자 앞에 -w 플래그를 지정하면 콘솔에 텍스트를 표시하는 대신 HTML 문서를 현재 디렉터리의 파일로 써요.
인자 앞에 -k 플래그를 지정하면 사용 가능한 모든 모듈의 요약(synopsis) 줄에서 인자로 주어진 키워드를 검색해요(역시 Unix man 명령과 비슷). 모듈의 요약 줄은 문서 문자열의 첫 줄이에요.
또한 pydoc 을 사용해 방문하는 웹 브라우저에 문서를 제공하는 HTTP 서버를 로컬 머신에서 시작할 수도 있어요. python -m pydoc -p 1234 는 포트 1234 에서 HTTP 서버를 시작해 http://localhost:1234/ 에서 문서를 탐색할 수 있게 해요. 포트 번호로 0 을 지정하면 ... 사용 가능한 포트가 선택돼요.