Modern Python Projects Transcripts
Chapter: Documentation
Lecture: Testing your documentation
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
So we have our documentation with some code examples, and I'm not sure if you noticed, but I forgot to change the name.
0:09
Add subtract in those two examples. So, actually, if you run this line in the terminal, he's going to return you 4 instead of 0.
0:18
So far, when we were building, sphinx, documentation. sphinx wasn't checking if those code examples are correct,
0:24
but we can easily change that with yet another extension. So back to the conf.py.
0:30
And we have to add the DOC test extension, now to test the code examples. In our documentation, we have to run, make doctest and we have 6 failures.
0:48
That's because sphinxes not smart enough to figure out that this add function is the function that we are actually documenting right now,
0:57
so you have to be very explicit in your code Examples. If you want to use the add function, you have to actually first imported.
1:05
Let's go back to our doc strings and let's fix them. So first we have to import add function from math operations.
1:17
The same here. Let's leave this back for now, and I think we're good. Let's go to the calculator as well. Yep. Same thing here. I think we're good.
1:40
Let's run the doctest again. So we have 9 tests, 3 failures, and this time none of them is about missing function or method.
1:55
So the first error comes from here. When we assign an expression to a variable in a Python terminal,
2:00
we don't get any output. But I accidentally put calculator five year. So let's delete this line and then we have a problem with this add function.
2:13
So here we have to actually replace add with subtract function. Perfect nine tests, no failures.
2:27
The build was successful, So running doctest is a great way to make sure that your documentation stays up to date.
2:33
But you also have to remember to explicitly import all the functions and classes that your going to call in your code examples.