pydoc — 설명서 생성과 온라인 도움말 시스템

소스 코드: Lib/pydoc.py

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. For example, running

python -m pydoc sys

를 셸 프롬프트에서 실행하면, sys 모듈의 설명서를 유닉스 man 명령으로 표시되는 매뉴얼 페이지와 비슷한 스타일로 표시합니다. pydoc의 인자는 함수, 모듈 또는 패키지의 이름이거나 모듈이나 패키지의 모듈 내의 클래스, 메서드 또는 함수에 대한 점으로 구분된 참조일 수 있습니다. pydoc에 대한 인자가 경로처럼 보이고 (즉, 유닉스의 슬래시와 같이 운영 체제의 경로 구분 기호가 포함되어 있으면), 기존 파이썬 소스 파일을 가리키면, 해당 파일에 대한 설명서가 생성됩니다.

참고

In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.

출력을 콘솔에 인쇄할 때, pydoc은 읽기 쉽도록 출력을 페이지로 나누려고 합니다. PAGER 환경 변수가 설정되면, pydoc은 그 값을 페이지 매김 프로그램으로 사용합니다.

인자 앞에 -w 플래그를 지정하면 콘솔에 텍스트를 표시하는 대신, HTML 설명서가 현재 디렉터리에 파일로 기록됩니다.

인자 앞에 -k 플래그를 지정하면 인자로 주어진 키워드에 대해 사용 가능한 모든 모듈의 개요 행을 검색할 수 있습니다. 역시 유닉스 man 명령과 유사한 방식입니다. 모듈의 개요 행은 설명서 문자열의 첫 행입니다.

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting web browsers. python -m pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred web browser. Specifying 0 as the port number will select an arbitrary unused port.

python -m pydoc -n <hostname> will start the server listening at the given hostname. By default the hostname is ‘localhost’ but if you want the server to be reached from other machines, you may want to change the host name that the server responds to. During development this is especially useful if you want to run pydoc from within a container.

python -m pydoc -b will start the server and additionally open a web browser to a module index page. Each served page has a navigation bar at the top where you can Get help on an individual item, Search all modules with a keyword in their synopsis line, and go to the Module index, Topics and Keywords pages.

pydoc이 설명서를 생성할 때, 현재 환경과 경로를 사용하여 모듈을 찾습니다. 따라서, pydoc spam을 호출하면 정확히 파이썬 인터프리터를 시작하고 import spam을 입력할 때 얻는 모듈의 버전을 설명합니다.

Module docs for core modules are assumed to reside in https://docs.python.org/X.Y/library/ where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.

버전 3.2에서 변경: -b 옵션이 추가되었습니다.

버전 3.3에서 변경: -g 명령 줄 옵션이 제거되었습니다.

버전 3.4에서 변경: pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.

버전 3.7에서 변경: -n 옵션이 추가되었습니다.