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

[Cameron Simpson]

On 25Apr2020 23:22, boB Stepp <robertvstepp at gmail.com> wrote:
>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. [...]
>[...]  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?

I do this, sometimes, if the function or class is amenable to a doctest 
which reads nicely. Here's one:

    https://pypi.org/project/cs.context/

and I intend to adopt this practice more in the future. The nice thing 
about a doctest is that it is right next to the code. As you say, a 
nicely written one doubles as a nice example for the docs.

Cheers,
Cameron Simpson <cs at cskk.id.au>