Seamless sync between docs/ and examples/

[lazyoracle]

Describe the missing feature

Most of the playbook documentation under docs/ is derived from the notebooks in examples/. However, while we have CI checking the notebooks never go out of sync and are always updated with breaking code changes, this is not the case for the playbooks in the documentation.

Describe the solution you'd like

The current workflow for generating the docs/ content from the notebooks in examples/ is to use jupyter nbconvert --to=rst examples/[notebook name].ipynb manually from the terminal and then committing the resulting rst files and images. This is obviously not great for ensuring stuff stays in sync.

We probably start enforcing this manually and then move to a more automated approach.

• Enforce updating example documentation in API breaking PRs
• Use jupyterbook to directly obtain the documentation from example notebooks.

Describe alternatives you've considered

• Manually checking the example documentation every few months to ensure things aren't out of date.
• Fixing things when a newcomer tries to use the code and ends up with examples that break on the latest version

Additional context

Add any other context or screenshots about the feature request here. Please feel free to suggest details about how you believe this feature request might be best implemented. If you have used similar features in other libraries, consider providing links or resources to example implementations.