update documentation

docs/developer/explanations/architecture.rst

@@ -37,10 +37,17 @@ the known expectations of the plan, passes it to the ``RunEngine`` and handles a
 The Service Object
 ^^^^^^^^^^^^^^^^^^
 
-Handles communications and the API layer. This object holds a reference to the worker 
-can interrogate it/give it instructions in response to messages it recieves from the message
-bus. It can also forward the various events generated by the worker to topics on the bus.
+Handles communications between the ``BlueskyContext`` and ``Worker`` and sets up subscriptions for
+publishing Bluesky event documents to the message bus. This object is injected as a dependency into
+(using the FastAPI_ dependency injection system) to all REST endpoints, exposing their methods to 
+the REST API.
 
+The REST API
+^^^^^^^^^^^^
+
+Exposes methods of the ``Worker`` to REST endpoints, which are used by the CLI as well.
+Written with FastAPI_, this layer also validates request and response bodies/parameters.
 
 .. _RunEngine: https://nsls-ii.github.io/bluesky/run_engine_api.html
 .. _IPython: https://ipython.org/
+.. _FastAPI: https://fastapi.tiangolo.com/lo/

docs/developer/how-to/update-openapi.rst

@@ -0,0 +1,14 @@
+Update the openapi schema
+-------------------------
+
+If you change any of the code in src/blueapi/service/main, it is imperative that
+you update the openapi schema to reflect these changes. There is a test to check
+that this has been done.
+
+Simply type,
+```
+blueapi schema -u
+```
+
+To update. You can also specify a `-o` tag to generate the schema elsewhere - note
+this doesn't work in combination to the `-u` tag.

docs/developer/index.rst

@@ -34,6 +34,7 @@ side-bar.
             how-to/static-analysis
             how-to/lint
             how-to/update-tools
+            how-to/update-openapi
             how-to/make-release
 
         +++

docs/user/how-to/configure-app.rst

@@ -15,5 +15,17 @@ and simply pass it to the CLI by typing::
     $ blueapi --config path/to/file.yaml
 
 where ``path/to/file.yaml`` is the relative path to the configuration file you
-wish to use. Then, any subsequent calls to child commands of blueapi will
-use this file.
+wish to use.
+
+Note: child commands
+--------------------
+Configuration options need to be passed down to child commands. For example,
+if you start the server with::
+    $ blueapi --config path/to/file.yaml
+
+And then use the CLI to discover the devices with::
+    $ blueapi controller devices
+
+The configuration for the second command will be different to the first. You
+must supply the correct configuration in this case::
+    $ blueapi --config path/to/file.yaml controller devices

docs/user/how-to/use-cli.rst

@@ -0,0 +1,39 @@
+Use the command line interface (CLI)
+====================================
+
+Blueapi comes pacakged with a simple click based CLI. You can start the server
+and then query it for plans and devices, as well as ask it to run a plan, through
+the CLI.
+
+Starting the server
+-------------------
+You can start the server and optionally specify configuration options (see the
+documentation section on how to :doc:`configure blueapi <./configure-app>`) with
+the following command::
+    blueapi serve
+
+The default configuration options for this command will start up the server using 
+startup scripts found in `src/blueapi/startup` - this will initialise the server
+with existing plans and devices that can be run with those plans.
+
+Find devices
+------------
+A list of all usable devices can be retrieved with the following command::
+    blueapi controller devices
+
+Find plans
+----------
+A list of all plans runnable by the server can be queried with::
+    blueapi controller plans
+
+Run a plan
+----------
+To run a plan, you must specify a valid name of a plan with correct parameters.
+The 'sleep' command would need to be run like so::
+    blueapi controller run sleep '{"time": 2.0}'
+
+where `2.0` can be any number. By default, the worker will try to run the plan
+until completion, but you can specify a timeout::
+    blueapi controller run sleep '{"time": 2.0}' -t 1.0
+
+In this case, this will fail with a timeout error.