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
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.

Talk Python's Mastodon Michael Kennedy's Mastodon