Modern Python Projects Transcripts
Chapter: Let's build a CLI
Lecture: Adding documentation
0:00 One last thing that we have to do is to add some documentation, to our code. So I went ahead and I documented all the functions in my
0:09 uptimer file. They're quite simple, one line summary, and then I document the parameters and I do this for all
0:16 the functions here. So next we're going to call sphinx and generate the scaffolding of our documentation. So we're on the Sphinx.
0:31 Quick start command. And then, as always, we have to answer some questions. I use separate directories for source and build.
0:48 Okay, let's go back to the code editor. And now we have two folders source and build. Build is empty, and source contains the usual stuff.
0:57 So the index.rst file and the conf.py, let me replace that with some text that I wrote before. So, basically,
1:05 I have two sentences explaining what this tool does. A quick start explaining how to install poetry and how to use poetry.
1:13 to run our uptimer, and then I have a table of content that will contain api.rst. So, we have to add this file and again let me copy some text here,
1:25 so I used the automodule sphinx extension to automatically extract the documentation from all the functions in the uptimer, and to display
1:34 them in this page. So to make this work, we actually have to go to the conf.py and add this autodoc to the list of extensions.
1:45 So, we go here and we at the autodoc and the viewcode so we can click this link to see the source code directly in the documentation.
1:54 And one last thing that we have to do before we leave this file, is to go up and add the parent directory to the system path.
2:02 That's because we are currently in the source directory and our uptimer lives in the uptimer directory. So currently,
2:09 if we run the make command from the source directory, it won't be able to find the files that live in this uptimer directory.
2:17 So, let's just change this 1 dot to two dots(..) and now the parent directory of source.
2:23 So, the whole uptimer folder with our project is in the system path, and I think we're good to go.
2:29 So, let's go to the terminal and let's generate the documentation. As always, we have to use, poetry run make not just make.
2:42 So, we have the HTML in the build.html. Let's go there and let's open index in the browser. Cool. So we have the basic documentation of our uptimer.
2:57 We have the quick start section and we have a link to the API documentation. If we go here, you can see the documentation of two methods and the source
3:06 code for them. Two methods. So, what happened with the last one? So, if we go to the uptimer,
3:14 we have this check method, but apparently it's not documented here.
3:18 That's because methods decorated with this click command param not by default documented.
3:23 So we have to add this function manually to the documentation. So we go back to api.rst. R S t and we use the autofunction module,
3:33 and we specify that we want to document the function called Check. Let's rebuild the documentation and now we have the check command.
3:52 One last thing that we can do is to use a plugin called Sphinx-click, to extract, the click documentation for our method.
4:01 You will see in a moment how it looks like. So, first we have to install it. Now we have to enable it.
4:20 And now in the index.rst, I want to show how to use my uptimer from the CLI, and this can be achieved with this click sphinx extension.
4:34 So, I want to explain here how to use the CLI command. So, I add header And then I add this directive that you can find in the
4:42 Sphinx Click documentation. Let's recreate the documentation. And if we go back to the main page of our documentation,
4:55 you see that we have a CLI command section and here we have uptimer and all that is automatically extracted by Sphinx.
5:03 So, we have the documentation for our function, and we also have the example of how to use it in the command line.
5:10 And we also have a bug here because URL is not an optional argument So, let's fix that. If we go to the uptimer, when we specify
5:22 nargs, it changes the your url argument when optional one, I think we have to add required=True. to make the required again.
5:37 Okay, it's not changed. So let's actually try to change something in the documentation because I think if you only change the parameters in the code,
5:47 not the documentations sphinx has some caching that doesn't get busted. Or maybe I'm using wrong parameter.
6:07 Nope, I'm using the right argument required, Let's remove it and added again.
6:34 Okay, so there was some issue with the cache. But now you where else is required argument. So, we have a starting point for our documentation.
6:44 You can add more sections. You can add more documentation to some API
6:48 methods that you write in the future and they will be automatically added to the api.rst Now you can write some tutorials or how to sections explaining
6:57 how to use your uptimer with some new features.