DOC - Improvement: Making example code executable

[ianhi]

Problem

Code in the docs can have typos, or may work when it was written but becomes out of date with underlying changes. We need a way to regularly run the example code in the docs.

Solutions?

I think there are two approaches to this.

1. Transform the docs and include them as part of the test suite

Conceptually just extracting the python and running it, but there is some complexity. That can be managed by somethign like: https://github.com/koaning/mktestdocs

However it does not seem like any of the existing solutions will easily allow us to manage the code blocks where the user chooses between local and s3 storage so that's one potential roadblock.

2. Swap the docs framework to something that natively understands executable documents. e.g. with myst markdown based docs. Then the code can be executed as part of the docs. I personally like this solution as it also lends itself towards allowing a reader to open a jupyterhub with the docs page, but it is python centric and would require redoing the docs configuration.

[paraseba]

@jhamman may have opinions on this. He recently migrated us to readthedocs