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