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