Modern Python Projects Transcripts
Chapter: Testing code
Lecture: Testing code examples in the documentation

Login or purchase this course to watch this video and the rest of the course contents.
0:00 One of the things that we usually forget to keep up to date is the documentation
0:04 mostly because we don't have a tool that will tell us when it's outdated and it's no longer valid. pytest can solve part of this problem.
0:14 If you put some code examples in your documentation, it can evaluate them and tell you when they are no longer working. Take a look at this function.
0:22 We have a documentation that specifies how to use it, but actually the documentation is incorrect.
0:28 But if we run pytest with --doctest-modules, parameter, it will check for parts of your documentations,
0:35 starting with this triple right angle bracket(>>>). If it finds any line like that, pytest will treat the following text as Python code,
0:44 and it will check that the result of this code is equal to the next line in the documentation. If it's not,
0:50 it will report an error. So let's give it a try. And as you can see, pytest is complaining that there is a problem with docstring
1:03 of add_two_numbers function. It was expecting 5, because here was specified 5. But actually the result of adding two numbers was 4.
1:15 So that's a pretty cool way to test that code examples in your documentation are upto date.

Talk Python's Mastodon Michael Kennedy's Mastodon