Document Your Python Code and Projects With ChatGPT

Using the Target Code as Part of Your Prompts

The quickest way to create prompts for writing docstrings is to include the target code as part of the prompt itself. Consider the following example, where you create a prompt for generating the docstring of a function that adds two numbers together:

You: Write a single-line docstring for the following function:

Python

def add(a, b):
    return a + b

ChatGPT:

Python

def add(a, b):
    """Return the sum of a and b."""
    return a + b

In this prompt, you ask ChatGPT to write a single-line docstring for your function. The result is quite straightforward and readable. This type of docstring doesn’t provide detailed information about the arguments and the return value of your function.

You can make your prompt a bit more detailed and ask for a specific docstring style. The following prompts make ChatGPT generate docstrings for your add() function using Google, NumPy, and Sphinx styles, respectively:

You: Write a Google-style docstring for the following function:

Python

def add(a, b):
    return a + b

ChatGPT:

Python

def add(a, b):
    """Sum two numbers.

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

    Returns:
        int or float: The sum of the two numbers.
    """
    return a + b

You: Write a NumPy-style docstring for the following function:

Python

def add(a, b):
    return a + b

ChatGPT:

Python

def add(a, b):
    """
    Sum two numbers.

    Parameters
    ----------
    a : int or float
        The first number to be added.
    b : int or float
        The second number to be added.

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

You: Write a Sphinx-style docstring for the following function:

Python

def add(a, b):
    return a + b

ChatGPT:

Python

def add(a, b):
    """
    Calculate the sum of two numbers.

    :param a: The first number.
    :type a: int or float
    :param b: The second number.
    :type b: int or float
    :return: The sum of the two numbers.
    :rtype: int or float
    """
    return a + b

These three docstrings look more complete and polished than the single-line docstring that you saw before. When you add information about the specific style that you want to use, ChatGPT can generate complete docstrings for your function. Of course, the initial result may not be perfect, but it’s a good starting point.

The most important point is that you’ve gotten complete docstrings by using a single, short sentence as a prompt. This is an incredible productivity boost for your project.

ChatGPT not only allows you to generate docstrings for functions. It can also take modules, classes, and so on. Here’s a short example of how to generate a docstring for a Circle class and its methods:

You: Write NumPy-style docstrings for the following class and its methods:

Python

class Circle:
    def __init__(self, radius):
        self.radius = radius

    def calculate_area(self):
        return round(math.pi * self.radius ** 2, 2)

ChatGPT:

Python

class Circle:
    """
    A Circle class to perform some circle-related operations.

    Parameters
    ----------
    radius : float
        The radius of the circle.

    Attributes
    ----------
    radius : float
        The radius of the circle.

    Methods
    -------
    calculate_area():
        Calculates the area of the circle.
    """

    def __init__(self, radius):
        """
        Constructs all the necessary attributes for the circle object.

        Parameters
        ----------
        radius : float
            The radius of the circle.
        """
        self.radius = radius

    def calculate_area(self):
        """
        Calculate the area of the circle.

        Returns
        -------
        float
            The area of the circle rounded to 2 decimal places.
        """
        return round(math.pi * self.radius ** 2, 2)

Wow! That was neat! With a single-sentence prompt, you’ve made ChatGPT generate NumPy-style docstrings for your class and all its methods. That’s a great addition to your codebase.

Including Only Signatures in Your Prompts

Sometimes, you can’t use the target code as part of your prompts. This may be due to privacy requirements, or maybe you just want to keep your company’s code safe. In this scenario, you can create prompts that only use the signature of your classes, methods, and functions.

To understand how to create these types of prompts, consider the signature of a function that checks if a number falls within a given interval:

You: Write a Google-style docstring for a function with the following signature:

Python

def in_interval(number, start, end):

ChatGPT:

Python

def in_interval(number, start, end):
    """
    Checks if a given number is within a specified interval.

    This function takes three arguments: a number, and the start
    and end points of an interval.
    It checks whether the given number falls within the specified
    interval or not.

    Args:
        number (int or float): The number to check.
        start (int or float): The starting point of the interval.
        end (int or float): The ending point of the interval.

    Returns:
        bool: True if the given number falls within the interval,
        False otherwise.

    Raises:
        ValueError: If the start is larger than the end, or if
        the number, start, or end are not numbers.
    """

In this example, the function’s signature is the only context that you provide to ChatGPT. The LLM is smart enough to examine the function’s name and arguments and generate a suitable docstring for you. Note that having descriptive function and argument names is key in this kind of prompt. Otherwise, the output may not be good enough.

In most cases, adding type hints to the function’s signature will improve the quality of the generated docstring.

Writing Prompts That Use No Code

You can also craft a prompt by just describing the input and output of your code or by providing a detailed description of what your code does. Again, these types of prompts are useful when you’re not allowed to upload your code as part of your prompt.

To illustrate, here’s a prompt that asks ChatGPT to write a docstring for a function that determines whether an integer number is prime:

You: Write a Google-style docstring for a function that takes an integer as an argument and determines whether it’s a prime number.

ChatGPT:

Python

def is_prime_number(n):
    """
    Determines if an input integer is a prime number.

    This function takes an integer as an argument and checks
    whether it is a prime number. A prime number is a
    positive natural number greater than 1 that has no positive
    integer divisors other than 1 and itself.

    Args:
        n (int): The integer to check.

    Returns:
        bool: True if the input integer is a prime number,
        False otherwise.

    Raises:
        ValueError: If n is less than or equal to 1.
    """

This docstring is quite complete and useful. It even includes an explanation of what a prime number is, which is great! You can tweak it further and polish a few details. However, you already have a great starting point.

Asking for Tests and Usage Examples in Your Prompts

Usage examples are probably the most important part of good software documentation. Through code examples, your users can quickly understand how to use your code and how it works. Often, other developers will scan through your documentation until they find a code example.

So, adding usage examples to your docstrings is a big plus. With ChatGPT, providing usage examples is just a matter of including a short sentence in your prompts. Consider the following prompt and its output:

You: Write a NumPy-style docstring for the following function. Add a section with usage examples as doctest tests:

Python

def add(a, b):
 return a + b

ChatGPT:

Python

def add(a, b):
 """
 Add two numbers together.

 This function takes two numbers (either integers or floats)
 as arguments and returns their sum.

 Parameters
 ----------
 a : int or float
     The first number to add.
 b : int or float
     The second number to add.

 Returns
 -------
 int or float
     The sum of the two input numbers.

 Examples
 --------
 >>> add(1, 2)
 3
 >>> add(5.5, 2.5)
 8.0
 >>> add(100, -50)
 50
 """
 return a + b

The highlighted lines show the usage examples for your function. In the prompt, you instructed ChatGPT to use the doctest test format for the examples. This will provide two important assets:

1. Usage examples
2. Basic tests for your code

That’s neat! You’ve gotten two benefits in one shot! Your documentation has cool usage examples for your user, and at the same time, it has tests that will help you make your code more robust. You can run these tests using the doctest command.

Creating README Files

A README file is arguably the most basic piece of external documentation that you’ll ever create for any Python project. You’ll probably find many different recommendations about what to include in your README files. In general, the content of this file will depend on your specific project and its main goals.

You can rely on ChatGPT when creating a README file for a given project. If you don’t have a clear idea of what to include in this type of file, then you can ask ChatGPT:

You: What are the recommended guidelines for writing a README file?

ChatGPT: Writing a good README file is important to help users understand the purpose of your project, how to use it, and how to potentially contribute to it. Here are some common sections that are often included in a well-written README file:

1. Project Title: A brief, catchy title at the beginning of the README.

2. Project Description: A couple of paragraphs describing the project, what it does, and its purpose.

3. Installation and Getting Started: Detailed instructions on how to install the project and any dependencies, how to set it up, and how to get it running. For a software project, include the necessary command lines.

4. Usage Examples: Show samples on how to use the project. Code snippets and screenshots can be very useful in this section.

5. Contribution Guidelines: If your project is open source and you’re accepting contributions, specify how to contribute and submit pull requests to your project. You might include code style preferences, automatic tests they should pass, and so forth.

6. Licenses: Note the project’s license type.

7. Contact Information: Provide your contact information or guidelines on how to get support.

8. Credits and Acknowledgements: Where necessary, give credit to related work or resources you have utilized.

Keep your README clear, concise, and informative. Remember, it is generally the first thing people will see when they visit your project, and it could greatly influence their decision to use or contribute to it.

Of course, this list isn’t complete or definitive. You may need some other sections depending on your specific project. However, the output provides a great starting point for a great README file.

Now, you can select the best structure for your file and then create specific prompts for ChatGPT to help you write each section. Start off with the title:

You: Write five engaging titles for the README file of a Python project that provides basic math operations.

ChatGPT:

1. “Welcome to PyBasicMath: Your One-Stop Solution for Basic Mathematical Operations in Python”
2. “PyBasicMath: Simplifying Complex Calculations with Basic Mathematical Functions”
3. “Math Made Easy with PyBasicMath: A Complete Python Package for Basic Calculations”
4. “Unleash the Power of Mathematics with PyBasicMath: Quick and Efficient Python Math Operations”
5. “PyBasicMath: Making Mathematics Approachable for Python Developers of All Levels”

This is a great list of title suggestions. You probably like some of them already, but you can also pick ideas from several of these suggestions and develop a great title yourself. Go ahead and try writing prompts for other sections. You’ll be surprised at how helpful ChatGPT can be.

As an exercise, you can go ahead and write specific prompts to generate the rest of the sections that ChatGPT suggested above.

Asking ChatGPT for help creating the README file piece by piece rather than asking it to generate the whole README file may be more convenient and effective because you can tweak the prompt to target a specific section.

Generating Code Explanations

ChatGPT can generate a detailed explanation of how a piece of code works. This possibility opens a great opportunity for you to create external documentation. Here’s a prompt that asks the LLM to explain how a function works:

You: Explain how the following function works:

Python

def find_extremes(iterable):
    data = tuple(iterable)
    if len(data) == 0:
        raise ValueError("input iterable must not be empty")
    return min(data), max(data)

ChatGPT:

The find_extremes(iterable) function finds the smallest and largest values in an iterable such as a list, tuple, or any other Python iterable object. Here’s a step-by-step breakdown:

1. data = tuple(iterable): This line of code converts the input iterable into a tuple. Regardless of whether the input is a list, a set, or another type of iterable, by converting it into a tuple, it ensures that the data can be iterated through consistently in the next steps.

2. if len(data) == 0: raise ValueError("input iterable must not be empty"): If the length of the tuple data is zero (i.e., if the input iterable is empty), a ValueError exception is raised with the message “input iterable must not be empty”. This acts as a guard clause, preventing the function from proceeding with an empty iterable, which would cause the min and max functions to also raise a ValueError.

3. return min(data), max(data): This line uses the built-in Python functions min and max to find the smallest and largest values in the iterable, respectively. These values are returned as a tuple.

If the function can compare elements within data, it determines the smallest and the largest values. If not (e.g., iterable is a complex object that doesn’t implement a comparison operation), the min and max functions will raise a TypeError.

Overall, this function takes any iterable and returns a tuple representing the smallest and largest values present in the iterable.

ChatGPT’s output is quite detailed and explains how the function works line by line. This piece of explanation will be a great addition to the external documentation of your project. You can use this explanation in a tutorial, a how-to guide, or even in a README file if that’s appropriate for the project at hand.

Creating Usage Examples

You’ve already learned that ChatGPT can generate usage examples as part of your docstrings. It can also generate usage examples that you can then use in a tutorial, a how-to guide, or a README file:

You: Write three usage examples for the following function. Add explanations to each example:

Python

def is_divisible(a, b):
    if not a % b:
        return True
    return False

ChatGPT:

The is_divisible(a, b) function checks whether one number (a) is completely divisible by another number (b). It uses the modulus operator (%), which returns the remainder of the division of a by b. If the remainder is 0, it indicates that a is completely divisible by b.

Python

print(is_divisible(10, 5))  # Returns: True

In this example, the function is checking if 10 is divisible by 5. Since 10 divided by 5 gives a quotient of 2 without any remainder, the function returns True.

Python

print(is_divisible(17, 3))  # Returns: False

In this case, the function is checking if 17 is divisible by 3. As 17 divided by 3 gives a quotient of 5 and a remainder of 2, the function returns False.

Python

print(is_divisible(36, 9))  # Returns: True

Here, the function checks whether 36 is divisible by 9. As 36 divided by 9 gives a quotient of 4 with no remainder, the function returns True. It indicates that 36 is completely divisible by 9.

Note that your prompt includes the specific number of examples that you want. It also asks for individual explanations. You can add more detailed instructions about other aspects of your code as well. For example, you can ask for specific edge cases, like when the second argument is 0.

Detailed instructions will improve the quality of the generated output and direct the explanation toward specific and important behaviors of your code that can be useful for your users.

Writing Tutorials and How-to Guides

Now that you’ve used ChatGPT to generate code explanations and usage examples, you can assemble them and develop a tutorial or a how-to guide for your code.

For example, say that you want to create a tutorial about using a Python library that performs basic math calculations. If you’ve used a single ChatGPT thread to generate the code examples and explanations for the library, then the chat has enough context to generate title suggestions, an outline, an introduction, and even a good conclusion.

Here’s a short prompt that asks ChatGPT to generate an outline for a tutorial:

You: Write an outline for a tutorial on a Python library that performs basic math calculations.

ChatGPT:

Outline for Python Basic Math Library Tutorial

Introduction

1. Brief Introduction for the Tutorial
2. Understanding the Importance of Mathematics in Programming
3. Introducing the Python Basic Math Library:
   • What is the Python Basic Math Library?
   • What functions does it include?

Getting Started

1. Installing the Python Basic Math Library
2. Importing the Library into Your Python Project

Deep Dive Into Basic Math Functions

1. Addition:
   • Syntax and Parameter Information
   • Hands-on Example
2. Subtraction:
   • Syntax and Parameter Information
   • Hands-on Example
3. Multiplication:
   • Syntax and Parameter Information
   • Hands-on Example
4. Division:
   • Syntax and Parameter Information
   • Hands-on Example
5. Modulus:
   • Syntax and Parameter Information
   • Hands-on Example
6. Power:
   • Syntax and Parameter Information
   • Hands-on Example
7. Square Root:
   • Syntax and Parameter Information
   • Hands-on Example
8. Rounding Numbers:
   • Syntax and Parameter Information
   • Hands-on Example

Advanced Topics

1. Using Multiple Functions Together
2. Examples of Real-World Applications using Basic Math Library
3. Tracing Errors and Troubleshooting

Summary and Next Steps

1. Recap of Key Topics Covered
2. Where to Go Next: Other Mathematical Libraries in Python
3. Closing Remarks and Encouragement

Throughout the tutorial, we will be using practical sessions, hands-on exercises, use cases, and quizzes to make the learning process interesting and engaging. By the end of this tutorial, you will be proficient in using the Python Basic Math Library for various math operations.

Now, you can write specific prompts for ChatGPT to generate content for each section. You can also insert the usage examples and the code explanations in the appropriate sections. Go ahead and give it a try!

As you can see, ChatGPT is a great companion when it comes to documenting Python projects. However, before publishing any of the generated content, make sure you vet it all for accuracy and quality.