doc: Overhaul documentation

[maffettone]

Rearrange documentation to fit the diataxis model, and bring in content from recent publications, n2sn docs, and add new tutorials. This is a fairly large PR, but mostly recycles language from the existing docs or other reviewed sources. The focus here should be on ensuring the docs flow is accessible, the tutorials/how-tos work for people new to the codebase, with a small focus on proof reading.

Description

Documentation has been split into 4 sections:

1. Explainations
2. Tutorials
3. How-Tos
4. Reference

TODO

• [x] Clear all latent TODOs in docs
• [x] Adjust readme
• [x] refactor to follow diataxis using formatting of pydata/ophyd
• [ ] Get feedback and testing on all how-tos and tutorials.

Motivation and Context

Docs have been a sticking point on adoption in the community.

Review Request:

Please from scratch clone this repository:

git clone https://github.com/maffettone/bluesky-adaptive -b doc-overhaul
cd bluesky-adaptive
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
make -C docs/ html

Then in a browser, navigate to file:///bluesky-adaptive/docs/build/html/index.html

OR

Download the artifacts from GHA and in your browser navigate to file:// bluesky-adaptive-docs/index.html

And please focus on making sure tutorials and how-to's are clear and functional. The tutorials are involved and include bluesky pods, so you will need Podman on your system.

[maffettone]

Tagging @thomaswmorris for attention and review. (Wouldn't pop up in the dropdown for review).

[tacaswell]

I'm going to merge this as-is for operational expediency (we wanted to see built docs for a beamtime running today!).

Please still leave comments here and we will follow up on them.