[Tutor] Do you use doctests to show API use even when you normally use unit tests?

[boB Stepp]

Amazon delivered a new book to my doorstep today entitled "Practical
Programming, Third Edition -- An Introduction to Computer Science
Using Python 3.6", c. 2017, by Paul Gries, Jennifer Campbell and Jason
Montojo.  I am Easter egging through it and so far very much like it.
Early on the authors introduce type annotations and inserting doctests
 into their docstrings.  The latter is done for the first part of the
book as documentation on how to use the function it exists in, not to
run doctests.  Later in the book they start actually running the
doctests.  Near the end of the book they have a chapter on testing and
introduce unit tests using Python's unittest.  They discuss the
question of doctests versus unit tests, and, of course, heavily vote
for unit testing as the way to go.  However, they never stop inserting
doctests into their function and method docstrings.  I am assuming
that they consider it best practice as to how to document how to use a
function or method.

My question is:  Is this what you would consider to be best
documentation practice?

-- 
boB