[Proposal] Small POC for doctest and recipes to prevent docs drift from code

[jernejfrank]

The main motivation is to propose a mechanism to keep docs aligned with code. In particular, code examples in docs and docstrings that are stale because the code progressed but the docs we forgotten to be updated.

I experimented with this for our private repos and it proved handy. Our docs are a bit different since they do not have a cookbook/recipe layout, but I think it translates well over to here where we have large chunks of code in the docs.

2 additions:

1. There's a seperate doctest functionality which is already a Sphinx plugin and can be readily used for testing docstrings
2. A separate code embedding system for large parts that land in the test folder and get run as part of the CI

Under this split I would treat docstring code snippets directly relevant to that one class/function and it showcases directly its usage via simple examples tested via doctest.

Docs involving multiple classes/functions and documenting a workflow / full implementation get written as python script into a *.py file with asserts at the end so it becomes an executable test. These files get collected and executed as a test in pytest (marked docs) and can run separately on the CI.

One con is that the code and doc text live seperately (see proposed changes) which means you need two files open.