Wrote a bash script to test the example

This is not yet run in CI, but should check the example.

Author: rwb27

docs/source/quickstart/quickstart.rst

@@ -1,11 +1,20 @@
 Quick start
 ===========
 
-You can install `labthings-fastapi` using `pip`. Create a virtual environment for you project, then install labthings with:
+You can install `labthings-fastapi` using `pip`. We recommend you create a virtual environment, for example:
 
-.. code-block:: bash
 
-    pip install labthings-fastapi[server]
+.. literalinclude:: quickstart_example.sh
+    :language: bash
+    :start-after: BEGIN venv
+    :end-before: END venv
+    
+then install labthings with:
+
+.. literalinclude:: quickstart_example.sh
+    :language: bash
+    :start-after: BEGIN install
+    :end-before: END install
 
 To define a simple example ``Thing``, paste the following into a python file, ``counter.py``:
 
@@ -14,9 +23,11 @@ To define a simple example ``Thing``, paste the following into a python file, ``
 
 ``counter.py`` defines the ``TestThing`` class, and then runs a LabThings server in its ``__name__ == "__main__"`` block. This means we should be able to run the server with:
 
-.. code-block:: bash
 
-    python counter.py
+.. literalinclude:: quickstart_example.sh
+    :language: bash
+    :start-after: BEGIN serve
+    :end-before: END serve
 
 Visiting http://localhost:5000/counter/ will show the thing description, and you can interact with the actions and properties using the Swagger UI at http://localhost:5000/docs/.
 

docs/source/quickstart/quickstart_example.sh

@@ -0,0 +1,14 @@
+echo "Setting up environemnt"
+# BEGIN venv
+python -m venv .venv --prompt labthings
+source .venv/bin/activate  # or .venv/Scripts/activate on Windows
+# END venv
+echo "Installing labthings-fastapi"
+# BEGIN install
+pip install labthings-fastapi[server]
+# END install
+echo "running example"
+# BEGIN serve
+python counter.py
+# END serve
+echo $! > example_server.pid

docs/source/quickstart/test_quickstart_example.sh

@@ -0,0 +1,50 @@
+set -e
+
+# Run the quickstart code in the background
+bash ./quickstart_example.sh 2>&1 &
+quickstart_example_pid=$!
+echo "Spawned example with PID $quickstart_example_pid"
+
+# Wait for it to respond
+# Loop until the command is successful or the maximum number of attempts is reached
+ret=7
+attempt_num=0
+while [[ $ret == 7 ]] && [ $attempt_num -le 50 ]; do
+  # Execute the command
+  ret=0
+  curl -sf -m 10 http://localhost:5000/counter/counter || ret=$?
+  if [[ $ret == 7 ]]; then
+    echo "Curl didn't connect on attempt $attempt_num"
+
+    # Check the example process hasn't died
+    ps $quickstart_example_pid > /dev/null
+    if [[ $? != 0 ]]; then
+      echo "Child process (the server example) died without responding."
+      exit -1
+    fi
+
+    attempt_num=$(( attempt_num + 1 ))
+    sleep 1
+  fi
+done
+echo "Final return value $ret on attempt $attempt_num"
+
+# Check the Python client code
+echo "Running Python client code"
+(. .venv/bin/activate && python counter_client.py)
+
+
+# Get the spawned server's PID
+children=$(ps -o pid= --ppid "$quickstart_example_pid")
+kill $children
+echo "Killed spawned processes: $children"
+
+wait
+
+if [[ $ret == 0 ]]; then
+    echo "Success"
+    exit 0
+else
+    echo "Curl returned $ret, likely something went wrong."
+    exit -1
+fi