docs: restructure how-to and tutorial pages

[shree-iyengar-dls]

Fixes #1468

Changes made:

• Run Auth locally page moved to How-to Guides
• Run/Debug in a Developer Environment moves to How-to Guides
• Run in a Container moved to Tutorials
• Enable Persistent Volumes moved to Tutorials
• Integrate With Numtracker moved to Tutorials

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.93%. Comparing base (32c57b9) to head (9f1ce6a).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1564   +/-   ##
=======================================
  Coverage   95.93%   95.93%           
=======================================
  Files          44       44           
  Lines        3270     3300   +30     
=======================================
+ Hits         3137     3166   +29     
- Misses        133      134    +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[abbiemery]

I have added some dodal agnostic devices and plans that can be used for the tutorials. See #1577.

There will also need to be a change to the message bus page as it currently uses the docker compose command for the system tests, which people who do pip install blueapi will not have. This command should work:

echo "[rabbitmq_stomp].">enabled_plugins && podman run -it --rm --name rabbitmq-docs -v $(readlink -f enabled_plugins):/etc/rabbitmq/enabled_plugins:z -p 5672:5672 -p 61613:61613 rabbitmq:latest

Rest of the review to follow

[EmsArnold]

Some small general niggles - it might be good to put endpoint names in quotation marks (i.e. 'Set Active Task'), as well as responses (i.e. '201')

[EmsArnold]

I think the step above technically "creates" the task, while this one sets the task to be the "active task". Likely worth re-wording to be something along the lines of "Set the task created in the last step to be the active task, using the task_id generated"

[abbiemery]

I like the additions of using the docs page to run scans, this is how a lot of people use it currently.

This is perhaps a point of personal preference, but I think the tutorials section should be the really bare bones "hello world" of the app. The local install, load devices and plans into it, run a scan.

The more in depth and the more diamond specific stuff should be in the how-to's. Such as adding auth, configuring numtracker, using persistent volumes etc. Anything that requires you to have blueapi installed with dev dependencies, and certainly things that need docker compose etc should not be in tutorials.

This will result in a few pages on tutorials, and a rather full and comprehensive how to, but i think the split will help with clarification. Reading top to bottom through the docs should not have you jumping around with different assumed running/dev environments.

This PR, #1577, will add devices and the needed imports for running tutorials.

so the point of pip install blueapi and blueapi serve will give you an empty context, worth seeing.

Then do a step of, 'if we want to do anything we need devices and plans' . We've made some ones for you, so do pip install blueapi[demo] , then we load the devices via a config file (then link to another page in the how-to's about how to actually construct this file and what each bit means). blueapi -c config.yaml serve, and now you see devices, can run a plan etc.

uv run blueapi -c config.yaml controller run count '{"detectors": ["det"], "num":5}' -i cm1234-5
or
uv run blueapi -c config.yaml controller run step_scan '{"detectors":["det"], "params":[["stage.x",[0,5,1]]]}' -i cm1234-5

I appreciate that is a lot of text, so feel free to just keep calling me over in person if it makes life easier.