pydoc is a Python documentation generator. The module basically generates documentation from other Python modules. We can run the module directly from terminal in Ubuntu. In this article, we would discuss how to use Python documentation generator – pydoc.
The functionality of pydoc is pretty similar to the man command-line utility in Ubuntu. Even the built-in help() function in Python uses pydoc module to generate the documentation.
Furthermore, it primarily derives documentation from various modules through docstring and (in case docstring isn’t present) block of comments line in source file.
Use pydoc – documentation generator
In this section, we would discuss various options available with pydoc3 command-line utility.
Firstly, we would start with writing out an html file for the module. Hence, issue the following in terminal –
pydoc3 -w <module_name/package_name>
For instance,
pydoc3 -w math
It would save math.html in current directory.
Secondly, search for a particular keyword –
pydoc3 -k <search_term>
It will provide us a list of modules which contain the <search_term>. Herein, it will only look for synopsis lines of available modules.
For instance,
pydoc3 -k math
The output in the terminal may resemble –
test.test_cmath test.test_math cmath math
Thirdly, to make the documentation available of all the modules/package inside a web browser –
pydoc3 -b
Once you quit the web browser, it will display the following in terminal –
server>
Press b to launch browser again, or q to quit.
Fourthly, to start an HTTP server on a particular port –
pydoc3 -p <port_number>
It will start an HTTP server and ask us to launch a web browser. Press b to launch browser, or q to quit.
Alternately, we can also access the documentation through the web browser directly after we have run the above command in terminal. Type the following in address bar of our web browser –
http://localhost:<port_number>
For instance,
pydoc3 -p 9999
and, in web browser –
http://localhost:9999/
Lastly, to generate the documentation in terminal itself of a particular module –
pydoc3 <module_name>
For instance,
pydoc3 math
In conclusion, we have discussed how to generate Python documentation using pydoc module.
