diff --git a/docs/tutorials/local-auth.md b/docs/how-to/local-auth.md similarity index 100% rename from docs/tutorials/local-auth.md rename to docs/how-to/local-auth.md diff --git a/docs/tutorials/run-with-dev.md b/docs/how-to/run-with-dev.md similarity index 91% rename from docs/tutorials/run-with-dev.md rename to docs/how-to/run-with-dev.md index 60024caab5..028f2e61d7 100644 --- a/docs/tutorials/run-with-dev.md +++ b/docs/how-to/run-with-dev.md @@ -10,7 +10,7 @@ Ensure you are inside your virtual environment: source venv/bin/activate ``` -You will need to follow the instructions for setting up RabbitMQ as in [instructions for setting up RabbitMQ](run-bus.md). +You will need to follow the instructions for setting up RabbitMQ as in [instructions for setting up RabbitMQ](../tutorials/run-bus.md). The worker will be available from the command line (`blueapi serve`), but can be started from vscode with additional debugging capabilities. diff --git a/docs/how-to/write-devices.md b/docs/how-to/write-devices.md index 4fc1b8b949..5296731e25 100644 --- a/docs/how-to/write-devices.md +++ b/docs/how-to/write-devices.md @@ -23,5 +23,5 @@ The return type annotation `-> MyTypeOfDetector` is required as blueapi uses it The device is created via a function rather than a global to preserve side-effect-free imports. Each device must have its own factory function. :::{seealso} -[Numtracker integration](./integrate-with-numtracker.md) for how to configure where detectors write files. +[Numtracker integration](../tutorials/integrate-with-numtracker.md) for how to configure where detectors write files. ::: diff --git a/docs/tutorials/blueapi-docs-page.png b/docs/tutorials/blueapi-docs-page.png new file mode 100644 index 0000000000..b7e3f88be7 Binary files /dev/null and b/docs/tutorials/blueapi-docs-page.png differ diff --git a/docs/tutorials/find_devices.png b/docs/tutorials/find_devices.png new file mode 100644 index 0000000000..b442d02405 Binary files /dev/null and b/docs/tutorials/find_devices.png differ diff --git a/docs/how-to/integrate-with-numtracker.md b/docs/tutorials/integrate-with-numtracker.md similarity index 85% rename from docs/how-to/integrate-with-numtracker.md rename to docs/tutorials/integrate-with-numtracker.md index d52bd21747..08f6d03023 100644 --- a/docs/how-to/integrate-with-numtracker.md +++ b/docs/tutorials/integrate-with-numtracker.md @@ -6,7 +6,7 @@ You will need to [get numtracker itself configured for your instrument](https://github.com/DiamondLightSource/numtracker/wiki/new_beamline). -Blueapi needs [valid authentication configured](./authenticate.md) to communicate with numtracker. It will propogate its auth token so both blueapi and numtracker should be aware of who the user is and that they have permission to be on the instrument sessions (visits) that are intended for use. +Blueapi needs [valid authentication configured](../how-to/authenticate.md) to communicate with numtracker. It will propogate its auth token so both blueapi and numtracker should be aware of who the user is and that they have permission to be on the instrument sessions (visits) that are intended for use. ## Configuration diff --git a/docs/tutorials/put_task_with_details.png b/docs/tutorials/put_task_with_details.png new file mode 100644 index 0000000000..1d4fc9b80e Binary files /dev/null and b/docs/tutorials/put_task_with_details.png differ diff --git a/docs/tutorials/run-bus.md b/docs/tutorials/run-bus.md index f7d3b988be..8ad8ac2592 100644 --- a/docs/tutorials/run-bus.md +++ b/docs/tutorials/run-bus.md @@ -10,6 +10,11 @@ The worker requires a running instance of RabbitMQ. The easiest way to start it ```sh docker compose -f tests/system_tests/compose.yaml run rabbitmq --detach ``` +For those who use `pip install blueapi`, run: + +```sh +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 +``` ## Config File diff --git a/docs/how-to/run-container.md b/docs/tutorials/run-container.md similarity index 100% rename from docs/how-to/run-container.md rename to docs/tutorials/run-container.md diff --git a/docs/tutorials/run-plan.md b/docs/tutorials/run-plan-cli.md similarity index 100% rename from docs/tutorials/run-plan.md rename to docs/tutorials/run-plan-cli.md diff --git a/docs/tutorials/run-plan-docs.md b/docs/tutorials/run-plan-docs.md new file mode 100644 index 0000000000..33650db5be --- /dev/null +++ b/docs/tutorials/run-plan-docs.md @@ -0,0 +1,41 @@ +# Run a Plan from Docs page + +:::{note} +This page describes how to run a plan from the docs page for the p-xx testing rigs. +::: + +Following [this link](https://p46-blueapi.diamond.ac.uk/docs), will take you to the blueapi docs for p46. After keycloak login, you should see the page below. + +![BlueAPI docs page](blueapi-docs-page.png) + +Scrolling down will show you endpoints grouped. The different groups are described below. + +Definitions: +- Plan: a set of instructions for one aspect of experiment orchestration. More details can be found [here](https://blueskyproject.io/bluesky/v1.13.1rc1/plans.html) +- Task: one individual instance of the plan being run. +- Device: devices defined in ophyd-async(?). [This](https://blueskyproject.io/bluesky/v1.13.1rc1/tutorial.html#devices) is Bluesky's definition of a device. Maybe mention dodal here and add link? +- Environment - definition already provided +- Meta - definition already provided + +Steps for running a plan +1. Find available devices. + +The first recommended step is to find out what devices are available for use to run a plan. Scroll down to the Get Devices endpoint (/api/v1/devices) and Press the downwards arrow which should expand it to show to 'Try it out' button. + +![Find devices endpoint](find_devices.png) + +Next, press the 'Execute' button and scroll down to Responses where you should see available devices (e.g. 'det' in the example below). Select one of these devices. + +![Show devices](show_devices.png) + +2. Submit a task using one of the available devices. + +Scroll back up to the Submit Task endpoint (/api/v1/tasks). The default setting that should appear in the request body is the example of a 'count' task using detector 'x' and instrument session 'cm12345-1'. + +![Submit task default](submit_task.png) + +Press the 'Try it out' button and replace the placeholder 'x' in the request body with the device selected from step 1 ('det' in this example) and 'cm12345-1' with the correct instrument session details ('cm44194-1') which can be found on the #sscc-training-room slack channel. + +![Submit task with details](put_task_with_details.png) + +Troubleshooting diff --git a/docs/tutorials/show_devices.png b/docs/tutorials/show_devices.png new file mode 100644 index 0000000000..46327c2286 Binary files /dev/null and b/docs/tutorials/show_devices.png differ diff --git a/docs/tutorials/submit_task.png b/docs/tutorials/submit_task.png new file mode 100644 index 0000000000..3eefae6e00 Binary files /dev/null and b/docs/tutorials/submit_task.png differ diff --git a/docs/how-to/use-persistent-volumes.md b/docs/tutorials/use-persistent-volumes.md similarity index 95% rename from docs/how-to/use-persistent-volumes.md rename to docs/tutorials/use-persistent-volumes.md index 993307585d..73b28d2382 100644 --- a/docs/how-to/use-persistent-volumes.md +++ b/docs/tutorials/use-persistent-volumes.md @@ -5,7 +5,7 @@ BlueAPI can use persistent volumes as a scratch area. This allows the user to re ## Configuration :::{seealso} -[Configure the Application](./configure-app.md) +[Configure the Application](../how-to/configure-app.md) ::: The relevant configuration is below: