this is pretty much de facto in python, and though not as widely used as i'd like, there is a testing framework called doctest which allows you to write tests in the documentation.
so for a given method or class, you have a couplefew paragraphs which explain how to use it, with invocations that are run as part of the test suite.
sometimes there end up being too much acrobatics for this to be as useful as i'd like, but the basic idea is really neat, IMO.
Also a feature of Rust: Every example in your docs are tested with your unit tests (unless you explicitly turn it off for a specific example). It's also a useful way to check that you didn't change your API by mistake, or generally make sure your doc is up to date.
Doctest exhibits this idea but it only really works for small, self contained utility functions - e.g. slugify a string, round a number to 3 decimal places, etc.
so for a given method or class, you have a couplefew paragraphs which explain how to use it, with invocations that are run as part of the test suite.
sometimes there end up being too much acrobatics for this to be as useful as i'd like, but the basic idea is really neat, IMO.