Modern Python Projects Transcripts
Chapter: Let's build a package
Lecture: Add documentation
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
Next, Let's take a look at the documentation. So, we have the docs folder. We have a lot of sections set up by default,
0:09
which is good. So we have the read me file. We have the installation. We have the usage, modules. I'm actually going to rename modules to the API.
0:18
I Just because I like this name better. I also have to. There is actually no modules file here. So let me create one. I have too many tabs,
0:34
Okay, Back to the index rst. We have API contributing guide list of authors and the changelog.
0:42
that's good. So let's actually try to build the documentation. You have to go to the docs and we can run make HTML as we always
0:54
do. And we have a lot of errors. Let's start from the top. First, there is a warning that the static path does not exist,
1:04
and if we go here, you can see that yet there is no underscore static folder, but in the configuration,
1:16
we are specifying that all the HTML static files should be in it. So let's quickly create this folder.
1:27
And while we are here, you can see that We also should create underscore templates
1:32
folder for the template files. So if you want to use some HTML templates where
1:41
you would store the general structure of a page and then Only change the main text you would put those files inside this underscore templates folder.
1:51
On the other hand, if you not for sure that you don't need the templates
1:54
and the static files, you can simply remove those two settings from the configuration file Let's check the other warnings.
2:02
The rest of them complaints that the API file doesn't have a title. So, let's add one. Let's copy one of the existing ones.
2:11
Okay, this is all including files. Anything. Oh, usage. Let's leave the rest empty for now. One more try. Okay, This time it worked.
2:30
Let's see how the documentation looks by default, and it looks pretty fine. So what do we have here?
2:43
We have the main page, where we specify what uptimer is. We have a list of features that this that has to be actually filled in,
2:54
and we give credits to the cookie cutter py package. Next, we have the installation guide,
3:01
which is nice. Again, We get all this text from the cookie cutter template, so we don't have to write it by hand.
3:10
Next we have the usage, which is kind of incorrect because we want to show people how to use it in the command line.
3:16
So we will fix it, API that this empty for now, but we will fill it with the auto generated documentation. contributing guide again,
3:25
very detailed. I'm very happy that I don't have to write it by hand. credits Oh, I'm the development lead.
3:33
That's nice. And then we have the change log, All right, so we have to change a few things. First, let's add some documentation to the API Page.
3:43
So let me copy that. And let's rename the files, that should work.
4:02
Let's check, cool. So we have the helpers documented here. We also want to document how to use the main function.
4:17
But this thing will add to the user instruction let's rename it to quickstart. To use uptimer in your terminal.
4:46
I'm not even sure if that's a really website, but it doesn't really matter. I hope people will get it.
4:53
Let's copy the index RST from the previous version. This we don't need, because we already have that in the installation instructions.
5:07
Okay, you know what? Let's actually add click to the API as well. That looks like the most appropriate section.
5:14
And again we have to rename some things. It's not uptimer, it's CLI, and the function is called main, and the main function is still called uptimer.
5:24
So we leave it like that, back to the terminal. Oops! Unknown directive click. Okay,
5:36
so we actually forgot to add click extension to this configuration file. Let's go here and let's add it.
5:54
Perfect. Under the helpers, we have the documentation of how to use the uptimer. You can see this is how you call it in the terminal.
6:03
There are some options you can pass and the list of you where else. So, I think it's good enough to start. For a proper documentation,
6:15
There still a lot of things that you should add, but it's really up to you what information you want to include.
6:22
I will leave it like that because I don't want you to waste time watching me write some text in the RST file.
6:28
So let's actually move to something exciting and let's finally publish this package on pypi.