Documentation generation using the pydoc module in Python

PythonServer Side ProgrammingProgramming

Introduction

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

In this article you will be learning methods to view these documentations in various cases and even learn about docstrings that help you create your own documentation for your python scripts.

Now that you know the use of pydoc, let us get started.

Getting Started

The pydoc module comes packaged along with Python, which means you don’t have to download and install it separately.

In order to access pydoc, you can must first import it.

import pydoc

Accessing interactive shell using help() function

You can access the interactive shell in pydoc using it’s help function.

In order to do this, launch your terminal, and enter the python interactive shell.

Now, import pydoc and then use the pydoc.help() command to launch the interactive shell.

Example

>>>import pydoc
>>>pydoc.help()

Now, you can enter the name of the module, datatype, function, classes, etc., to obtain its documentation right from the interactive script.

Viewing documentation from the browser

If you want to view the documentation from the browser, you can do so easily using pydoc.

This time, you need not run the command through python shell. Rather you can provide it arguments and launch it directly.

To do so, launch your terminal and type the below command.

python −m pydoc −b

This should generate documentation for all the python modules, functions, objects present on your local system on the browser.

You can even search and retrieve specific keywords this way.

C:\Users\vijay>python −m pydoc −b
Server ready at http://localhost:50621/
Server commands: [b]rowser, [q]uit
server> q
Server stopped

Working with docstrings

Example

def documentation():
   '''Documentation using docstrings'''
print(documentation.__doc__)
help(documentation)

Output

Documentation using docstrings
Help on function documentation in module __main__:

documentation()
Documentation using docstrings

Conclusion

You now know how to view and read documentation of various python keywords, functions, modules, methods offline using the pydoc function.

You also learnt how to generate and create your own documentation using docstrings.

It is essential to maintain good documentation while working on large scale projects in order to know what you are doing where and avoid confusions later on in the future. It also helps prevent various unknown or runtime errors.

raja
Published on 11-Feb-2021 05:52:34
Advertisements