Basic tutorial on how to install and run

Author: rwb27

docs/source/index.rst

@@ -1,17 +1,13 @@
-.. labthings-fastapi documentation master file, created by
-   sphinx-quickstart on Wed May 15 16:34:51 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to labthings-fastapi's documentation!
+Documentation for LabThings-FastAPI
 =============================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   wot_core_concepts.rst
    quickstart/quickstart.rst
+   wot_core_concepts.rst
+   tutorial/index.rst
    dependencies/dependencies.rst
    concurrency.rst
    client_code.rst

docs/source/quickstart/.gitignore

@@ -0,0 +1 @@
+/settings/

docs/source/tutorial/index.rst

@@ -0,0 +1,13 @@
+LabThings-FastAPI tutorial
+==========================
+
+.. toctree:
+   
+   installing_labthings.rst
+   running_labthings.rst
+   writing_a_thing.rst
+   client_code.rst
+   blobs.rst
+   thing_dependencies.rst
+
+In this tutorial, we'll cover how to start up and interact with a LabThings-FastAPI server, how to write a Thing, and a few more advanced topics. It is intended as an introduction for someone using LabThings-FastAPI and/or writing Thing code to implement a new instrument. It doesn't detail all the internal workings of the library, but we hope this isn't needed for most people.

docs/source/tutorial/installing_labthings.rst

@@ -0,0 +1,28 @@
+Installing LabThings-FastAPI
+============================
+
+LabThings-FastAPI is a Python package, which is published to PyPI. You can install `labthings-fastapi` using `pip`. To see compatible versions of Python, please check PyPI_.
+
+It is common practice to use virtual environments in Python: this isolates projects from each other, and makes sure that installing packages for one project doesn't break other work you are doing. There are many ways of managing virtual environments in Python: if you are using a distribution like Anaconda, you may prefer to manage environments using the `conda` command or Anaconda interface. This tutorial uses the built-in `venv` module to create a virtual environment, but you can use whatever tool you are happy with.
+
+The commands below are all intended to be run in a terminal. We tend to use PowerShell on Windows, Terminal on a mac or your preferred terminal utility if you are on Linux. Note that most of our automated testing runs on Linux, and one or two commands are different on Windows. This is indicated with a comment (some text after a ``#`` character).
+
+It's always a good idea to check your Python version before you start, by running ``python --version``. This should print out something like ``Python 3.12.3``, although the exact version is not particularly important so long as it's up to date enough for the package to install. If this doesn't work, you likely need to install Python, which this tutorial doesn't cover. The Python website has instructions for most common operating systems.
+
+To create a virtual environment, run the following command:
+
+.. literalinclude:: ../quickstart/quickstart_example.sh
+    :language: bash
+    :start-after: BEGIN venv
+    :end-before: END venv
+    
+then install labthings with:
+
+.. literalinclude:: ../quickstart/quickstart_example.sh
+    :language: bash
+    :start-after: BEGIN install
+    :end-before: END install
+
+It is also possible to install LabThings from source, by cloning the GitHub repository and running ``pip install -e .[dev]``, but this is only recommended if you intend to alter the LabThings-FastAPI library; it is best to use the published package unless you have a good reason not to.
+
+.. _PyPI: https://pypi.org/project/labthings-fastapi/

docs/source/tutorial/running_labthings.rst

@@ -0,0 +1,33 @@
+Running LabThings-FastAPI
+=========================
+
+Each time you want to use LabThings-FastAPI, you will need to open a terminal and activate your virtual environment. If you created a virtual environment using the command on the :doc:`installing_labthings` page, you will need to change directory to the folder where you created your virtual environment (using `cd`) and then activate the virtual environment with `source .venv/bin/activate` or `.venv/Scripts/activate` (on Windows).
+
+Once you have activated the virtual environment, you should be able to run an example server with the command:
+
+.. code-block:: bash
+
+    labthings-server --json '{"things":{"/mything":"labthings_fastapi.example_things:MyThing"}}'
+
+This command will start a LabThings server, and will print the root URL for your server (by default, ``http://127.0.0.1:5000``). The ``127.0.0.1`` part means the server is only accessible from your computer, so you don't need to worry about other computers on your network accessing it.
+
+Now that your server is running, you should be able to view the interactive documentation in your web browser. There is an OpenAPI documentation page at ``http://127.0.0.1:5000/docs/``. This shows all the requests that the server supports, and even allows you to try them out in the web browser.
+
+Another important document is the Thing Description: this is a higher-level description of all the capabilities of each Thing in the server. For our example server, we have just one Thing, which is at ``http://127.0.0.1:5000/mything/``. This is a JSON document, but if you view it in Firefox there is a convenient tree view that makes it easier to navigate. Currently the Thing Description is not as interactive as the OpenAPI documentation, but it is rather neater as it's a higher-level description: rather than describing every possible request, it describes the capabilities of your Thing in a way that should correspond nicely to the code you might write using a Python client object, or a client in some other language.
+
+It is worth unpicking the command you ran to start the server: it has one argument, which is a JSON string. This is fine if you are starting up a test server for one Thing, but it gets unwieldy very quickly. Most of the time, you will want to start the server with a configuration file. This is a JSON file that contains the same information as the JSON string you passed to the command above, but in a more convenient format. To do this, create a file called `example_things.json` in the same directory as your virtual environment, and put the following content in it:
+
+.. code-block:: json
+
+    {
+        "things": {
+            "/mything": "labthings_fastapi.example_things:MyThing"
+        }
+    }
+
+You can then start the server using the command:
+
+.. code-block:: bash
+
+    labthings-server --config example_things.json
+