PyDoc in Python
PyDoc is a command line tool, just like perldoc in Perl. It is shipped with Python installation. It provides documentation on modules by enabling the user to pass the name of the module or its object and rendering the documentation page using the docstrings of the same module.
In order to run PyDoc, you need to use the -m flag of python in command prompt, which asks the command prompt to run the library module as a script.
$ python -m pydoc
pydoc - the Python documentation tool
pydoc <name> ...
Show text documentation on something. <name> may be the name of a
Python keyword, topic, function, module, or package, or a dotted
reference to a class or function within a module or module in a
package. If <name> contains a '\', it is used as the path to a
Python source file to document. If name is 'keywords', 'topics',
or 'modules', a listing of these things is displayed.
pydoc -k <keyword>
Search for a keyword in the synopsis lines of all available modules.
pydoc -p <port>
Start an HTTP server on the given port on the local machine. Port
number 0 can be used to get an arbitrary unused port.
pydoc -b
Start an HTTP server on an arbitrary unused port and open a Web browser
to interactively browse documentation. The -p option can be used with
the -b option to explicitly specify the server port.
pydoc -w <name> ...
Write out the HTML documentation for a module to a file in the current
directory. If <name> contains a '\', it is treated as a filename; if
it names a directory, documentation is written for all the contents.
Obtaining help from PyDoc over replace function of the str class.
$ python -m pydoc str.replace
Help on method_descriptor in str:
str.replace = replace(...)
S.replace(old, new[, count]) -> str
Return a copy of S with all occurrences of substring
old replaced by new. If the optional argument count is
given, only the first count occurrences are replaced.
This looks rather familiar to output of the builtin function help(), doesn't it? Actually, the builtin function help() is in fact being provided by the PyDoc module.
>>> help(str.replace)
Help on method_descriptor:
replace(...)
S.replace(old, new[, count]) -> str
Return a copy of S with all occurrences of substring
old replaced by new. If the optional argument count is
given, only the first count occurrences are replaced.
>>> import pydoc
>>> pydoc.help(str.replace)
Help on method_descriptor:
replace(...)
S.replace(old, new[, count]) -> str
Return a copy of S with all occurrences of substring
old replaced by new. If the optional argument count is
given, only the first count occurrences are replaced.
PyDoc even provides interactive browser documentation using an HTTP server. You can use the -p flag to specify the port to be used by the server. If you are not sure about ports, you can use the -b flag, which will assign an unused port to the server.
$ python -m pydoc -b Server ready at http://localhost:61165/ Server commands: [b]rowser, [q]uit server>
You can even generate documentation for your modules using the -w flag. I'll leave that to you as an exercise. Goodbye for now!