Sign in to continue learning
Team Software Engineering with AI
12h24m
Documentation comments are an important tool to help others understand your code and use it successfully. But it can be a pain to read these doc strings in IDEs or on GitHub. Luckily, tools exist to help you turn the documentation comments in your code into beautiful doc pages that make it easier for your colleagues and users to learn about your code. And if you aren't familiar with these tools and which options are available or how to install and work with them, you can always tap your LLM companion's knowledge of these tools. And the LLM will suggest some options for you and even how to set them up. For Python, Sphinx is the most comprehensive and widely used tool. So let's take a closer look at that. Sphinx is used in the Python community for generating documentation. It can convert restructured text doc strings into HTML, PDF, and many other formats, making it an essential tool for any developer looking to create professional documentation. Sphinx was created to generate documentation for the Python programming language itself, but is versatile enough to be used with any project. It takes your restructured text files and doc strings and turns them into a cohesive documentation site. It's capable of outputting in a variety of formats including HTML, Windows Help, LaTeX, EPUB, and a whole lot more. To get started with using Sphinx, you'll need to set it up. And this is another task that an LLM can assist with. If you ask the model for advice on how to install and set up Sphinx, it will walk you through the installation process step by step. You can provide context such as what system you're running on to get the best instructions for your particular setup. The first step is nice and easy. You can install it with pip. Note that if you want to follow along, you should probably do this in your own development environment. Once Sphinx is installed, the LLM states that you should run the Sphinx quick start command to set up a new Sphinx project. The script will give you some questions to answer. Usually, you can just accept the defaults or at least give sensible answers. One thing I would note though is that the default to keep the source and docs in the same directory is one that I override, and I like to keep them separate. I'll show my work in the screencast later on. This gives you a very basic Sphinx installation, and you saw how the quick start compiled a site for you. Next, you'll make some real code, work with ChachiPT to generate doc strings, and then see how to make sure it works with Sphinx to generate new documentation. So let's start with basic code like this, the circle area function from the previous videos. Start by working with an LLM to write a doc string for the function in the restructured test format, and again try giving it different roles or instructions until you get something that looks like the doc string here. And as you can see, the text in the comment is clear, and the structure follows the restructured text format, making it perfect for integration with Sphinx. Now at this point, you'll need a little bit of expertise in Sphinx to be able to get the most out of it, but if you don't have that, working with your favorite LLM will still get you up and running quickly. All of the following configuration code and instructions were provided to me by GPT by specifying that it's an expert in generating automatic documentation. I then provided it my code and asked it to help me set up Sphinx. Sphinx uses a configuration file called conf.py in Python for setting everything up. You should add code to this file to tell it where your source code is, and here's what I use for a directory I created in Colab called Sphinx Test. I'll show this in the screencast shortly. Depending on where you've put your source directory, you'll probably have a different URL there. Still in conf.py, you'll probably see extensions being set up as an empty list. If that's the case, use this line. If there's something in there already, don't overwrite it, but do add a string containing sphinx.ext.autodoc. For the Python earlier, I just created a Python file called area.py in the source directory. But in addition to that, you'll need another file with the .rst extension, and it looks like this. Sphinx uses this to figure out how deep in the doc string it goes to generate documentation. And then the master.rst file called index.rst will need to be updated to know about the area one that you just created. Once that's done, you can just call a command like make-html, and Sphinx will compile all of your code into docs. And the documentation for the area module that we wrote should look a bit like this. I know that I went through that quickly, so join me in the next video where I'll walk you through the process step by step.