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