Produce Documentation for Python Functions

In Python, documenting your functions is an important step that helps others understand what your code does, what inputs it expects, and what it returns. Python provides a built-in way to write documentation using docstrings.

By producing good documentation, you can make your code more readable and usable in larger projects or by external users.

Using Docstrings

A docstring is a string that appears just after the definition of a function. It describes what the function does, its parameters, and its return value. You write it using triple quotes (""" or ''').

Syntax

Following is the syntax for writing a docstring -

def function_name(parameters):
   """One-line summary.
   Optional detailed description.
   """
   # function code

Example

In this example, the docstring describes the purpose of the add() function, which is to add two numbers. It also specifies the parameters a and b and their types, as well as the return value (the sum of a and b) -

def add(a, b):
   """Add two numbers and return the result.

   Parameters:
      a (int or float): The first number.
      b (int or float): The second number.

   Returns:
      int or float: The sum of a and b.
   """
   return a + b

Accessing the Docstring

You can access (view) the docstring of a function using the built-in help() function or the .__doc__ attribute.

Example: Using help() Function

The help() function displays information about the function, including the docstring, as well as other useful metadata such as parameters and return values. Following is the way to use the help() Function -

def add(a, b):
   """
   Add two numbers and return the result.

   Parameters:
       a (int or float): The first number.
       b (int or float): The second number.

   Returns:
       int or float: The sum of a and b.
   """
   return a + b

# Use the help() function to view the docstring of the add function
help(add)

We get the output as shown below -

Help on function add in module __main__:

add(a, b)
   Add two numbers and return the result.

   Parameters:
       a (int or float): The first number.
       b (int or float): The second number.

   Returns:
      int or float: The sum of a and b.

Example: Using __doc__ Attribute

Another way to access the docstring is by using the .__doc__ attribute of the function. This returns the docstring as a string, and you can print it directly or use it in your code as needed -

def add(a, b):
   """
   Add two numbers and return the result.

   Parameters:
       a (int or float): The first number.
       b (int or float): The second number.

   Returns:
       int or float: The sum of a and b.
   """
   return a + b
print(add.__doc__)

Following is the output obtained -

Add two numbers and return the result.

Parameters:
   a (int or float): The first number.
   b (int or float): The second number.

Returns:
   int or float: The sum of a and b.

Standard Formats for Docstrings

It is helpful to use standard formats to make your code documentation easy to read. Some common formats are -

• reStructuredText (reST): A format used by tools like Sphinx to generate documentation.
• Google Style: A format that is simple and easy to read and is most commonly used.
• NumPy Style: A format generally used in scientific programming and libraries.

Example: Google Style Docstring

In the following example, we are defining a function multiply() that multiplies two numbers. The docstring explains the purpose of the function, the expected arguments, and the return value in a clear format -

def multiply(x, y):
   """Multiply two numbers.

   Args:
      x (int): First number.
      y (int): Second number.

   Returns:
      int: Product of x and y.
   """
   return x * y

Generating HTML Documentation

You can create complete HTML documentation from your docstrings using tools like:

• Sphinx: Converts docstrings written in reST format into professional HTML documentation.
• pdoc: A simpler tool that generates web-friendly documentation from Python code.
• pydoc: A built-in Python tool that can create simple text or HTML documentation.

Generating HTML Documentation Using pydoc

To generate an HTML documentation using pydoc, follow the steps given below -

Save Your Python File: First, make sure your Python code is saved in a file. Here, I am saving my file with the name greet.py on my desktop.

Open the Command Line Interface: Open the Command Prompt or PowerShell in Windows and use the cd command to go to the folder where greet.py is saved. For example, here in my case it is -

cd C:\Users\Tutorialspoint\Desktop

Run the pydoc Command:

Next, execute the following command in your command prompt -

C:\Users\Tutorialspoint\Desktop>python -m pydoc -w greet

Make sure you do not include the .py extension when running the command.

Check the Output:

This will create an HTML file named greet.html in the same directory (here, on my desktop). You will see a message like -

Add two numbers and return the result.

Parameters:
   a (int or float): The first number.
   b (int or float): The second number.

Returns:
   int or float: The sum of a and b.

wrote greet.html

Open the HTML File:

Finally, open the generated greet.html file in any web browser to view the documentation.

How to Write Good Function Documentation

Following are the simple tips to write a good function documentation -

• Start with a short one-line summary of what the function does.
• Specify the name and type for each parameter.
• Clearly describe the return value of the function.
• Provide examples if necessary to clarify usage.
• Keep your documentation concise, but make sure that it is accurate.