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