Modern Python Projects Transcripts
Chapter: Documentation
Lecture: Generating API documentation
Login or
purchase this course
to watch this video and the rest of the course contents.
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.