In Python, you can document your code using docstrings and then take advantage of them to enrich the project’s external documentation. ChatGPT can be of great help in writing both docstrings and external documentation.
In this tutorial, you’ll:
Build different ChatGPT prompts to generate Python docstrings
Use different styles while generating docstrings with ChatGPT
Add doctest tests and usage examples to Python docstrings
Create external documentation, such as README files and tutorials, with ChatGPT
To get the most out of this tutorial, you should have a ChatGPT account and know the basics of interacting with this tool using prompt engineering. You should also know the basics of how to document Python code.
Having high-quality, up-to-date documentation is critical for any software project. Poor documentation can cause a project to fail or go unnoticed even if the codebase is well written and the project’s main idea is innovative and useful.
Writing good documentation takes considerable time and effort. That’s why using large language models (LLMs) like ChatGPT can be a viable alternative for providing your projects and code with proper documentation.
Some of the benefits of ChatGPT for documenting Python code include the following:
Increased productivity: It allows automation of tasks related to code documentation and its maintenance, which saves you considerable time and effort.
Improved quality: It helps ensure that your documentation is accurate, up-to-date, and comprehensive.
Enhanced user experience: It can produce engaging and user-friendly documentation, leading to a better user experience.
Reduced costs: It helps reduce the costs of creating and maintaining documentation.
Improved compliance: It can help ensure that the documentation complies with standards and regulations, making it more consistent and professional.
With ChatGPT, you can generate cool documentation for your Python code in almost no time. In the following sections, you’ll learn the basics of using ChatGPT as an assistant for creating coherent docstrings and user-friendly external documentation for your Python projects.
The primary way to document Python code is through docstrings. In Python, a docstring is typically a triple-quoted string that occupies the first line of modules, functions, classes, and methods. This string has a special meaning for Python, which stores it in an attribute called .__doc__.
Many Python tools, including code editors and IDEs, take advantage of docstrings to provide real-time help when you’re writing your code. Docstrings are also part of Python’s built-in help system, which you can access with the help() function:
In this example, you call help() with the str class as an argument, and you get the class’s documentation page, which includes the class’s docstring:
In this case, you get the class’s docstring by accessing the .__doc__ attribute directly on the str class. As you can conclude, docstrings add a lot of value to your code. They’re the primary documentation that you and other Python developers will use to learn about any Python object.
You can also take advantage of your code’s docstrings when you’re building project documentation with a tool like Sphinx or MkDocs. These tools have plugins and features that allow you to extract the docstrings and make them part of your project’s external documentation, which can save you a lot of time.
Python has well-established conventions for writing good docstrings. Package, module, class, method, and function docstrings all have specific goals and should follow specific guidelines. You can find these guidelines and conventions in PEP 257.
Although PEP 257 provides a standard, you’ll actually find a healthy variety of docstring styles across the Python ecosystem. Here are a few common alternatives:
Google-style docstrings: This style comes from Google, and you’ll find many examples in the company’s open-source projects.
NumPy docstring standard: This style was developed for the NumPy library, and many other Python projects have adopted it.
reStructuredText (RST) or Sphinx docstring format: This style is based on reStructuredText and comes from Sphinx, which is a useful tool for automating documentation creation.
Epytext style: This is a lightweight markup language used to format docstrings, originally created by the Epydoc project.
Each style has its own conventions. Generally, you should choose one style and use it consistently throughout your Python project.
In practice, choosing a docstring style is mostly a matter of personal preference. However, you should also consider the specific needs of your project, including the following characteristics:
Your project’s complexity: If you have a large and complex project, then you may benefit from the Sphinx or NumPy style, which allows for detailed documentation. In contrast, small projects may just require basic documentation, and something like PEP 257 or Google-style docstrings will be okay.
Your documentation tools: If you use something like Sphinx or MkDocs to generate your project’s documentation, then you should use the style that has the best support in your tool of choice.
With this short background on docstrings in Python, you’re ready to start prompting ChatGPT to write some docstrings for you.
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:
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:
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:
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.
