Modern Python Projects Transcripts
Lecture: Generating API documentation
0:00 In our simple calculator module, we documented some of the functions.
0:04 Now it would be nice to display those doc strings in our documentation without having to
0:09 manually copy and paste it into those rst files.
0:13 Luckily Sphinx has a plugin that can extract documentation from your modules,
0:17 classes and functions. So let me show you how to do this.
0:21 First, we have to open the Sphinx configuration file and added the auto doc to
0:25 the list of enabled extensions. Next,
0:32 let's create a new file called API.rst that will store the API documentation.
0:41 Inside We have to specify which modules we want to show here.
0:45 So first I want to show the calculator class.
0:49 Let's make this a header and now I need to.
0:53 Add the directive that will auto generate the documentation from that module.
1:04 Now let's see if this works.
1:07 Let's go to the index.rst and let's add the API here.
1:15 Let's generate the documentation and no module calculator found.
1:23 So let's see, what we put here has to be a module that can be
1:27 imported from python. So when we start Python session,
1:30 we should be able to import calculator.
1:33 sphinx can't find this calculator model because it's generating the documentation from inside the source directory
1:41 and calculator leaves outside of this directory.
1:44 So what we have to do is we have to go to the configuration file and
1:49 we have to add the parent folder to the list of system paths.
1:54 Here is a short explanation of this problem.
1:57 Well, let's uncommented this and
2:00 Let's make sure we are adding the parent folders.
2:04 Let's save it and let's try one more time.
2:15 Perfect. Now it's working. Let's check if we actually see the API documentation, here,
2:21 let's refresh. And here we have the calculator.
2:25 I should name it differently and perfect.
2:28 As you can see, we have the documentation for the calculator class.
2:31 We have the documentation for the add method,
2:34 but we don't get the documentation for the other methods.
2:39 That's because only, the add method has a doc string.
2:43 If we add docsstrings to the other methods there will be also automatically displayed
2:47 in the documentation. Let's also add the documentation for the math operations file.
2:53 I go to the api.rst
2:56 Let's copy this. If, for example,
3:06 you want to document only one function from this file,
3:09 we could copy the name of the function,
3:13 and I did like here. So let's regenerate the documentation and let's go back to
3:24 the browser. So, as you can see,
3:26 we have the calculator and math operations here,
3:29 although I'm not happy that they are displayed like that.
3:31 So let's change. What we need to do is to
3:44 Add one higher level header in the a api.rst file.
3:53 And now I get a nice link to the API documentation.
3:56 And underneath I have the calculator and math operations.
4:01 displaying those docs strings here is pretty cool,
4:04 but we can actually have the source code included with yet another plugin.