How to view Python documentation using pydoc

📅 2019-Dec-29 ⬩ ✍️ Ashwin Nanjappa ⬩ 🏷️ ⬩ 📚 Archive

Python ships with a documentation generating and viewing tool called pydoc. This tool can be used to lookup and peruse documentation for everything in the Python standard library and also for your own modules and scripts. The tool can render documentation like a manpage or dump it to a simple HTML file or serve it from a local HTTP server.

• Every version of Python interpreter you have installed on your system ships with its own pydoc. For example, my Python 2.7 seems to have a pydoc2.7 and my Python 3.6 seems to have a corresponding pydoc3.6.

• There also seems to be a major version pydoc3 that is symbolically linked to one of the Python 3 versions:

$ readlink -m `which pydoc3`
/usr/bin/pydoc3.6

• The canonical pydoc is symbolically linked to one of the pydoc tools you have on your system. On mine it seemed to be linked to the Python 2.7 pydoc tool:

$ readlink -m `which pydoc`
/usr/bin/pydoc2.7

• To view Python documentation for a Python module or method at the shell:

$ pydoc os
$ pydoc os.path
$ pydoc os.path.join

This renders the docstring of the module or method colorfully formatted like a manpage. This is great for quick lookups at the shell in the midst of programming. This can be a great alternative to Googling or visiting the official Python guide online.

• To view Python documentation for your own foobar.py at the shell:

$ pydoc foobar

Note how the tool requires the module name, so we drop the .py file extension.

• To view the Python documentation in your local browser:

$ pydoc -p 9999

This serves up the Python documentation as HTML pages at the http://localhost:9999 URL. Once you open this URL in your local browser you can find the Python standard documentation rendered as simple formatted HTML webpages. Navigating to specific modules is not clear here. For example, I could not find os.path documentation listed at http://localhost:9999, but it was available when I specifically typed http://localhost:9999/os.path.html into the addressbar.

• To dump a simple formatted HTML documentation for a specific module, say write os.path documentation to os.path.html:

$ pydoc -w os.path

• To view Python documentation in a Tkinter GUI program:

$ pydoc -g

This threw up a Tkinter GUI tool, but it did not render the documentation.

Tried with: Ubuntu 18.04