Merge pull request #95 from labthings/docs_improvements

Docs improvements

Author: rwb27

.github/workflows/test.yml

@@ -97,6 +97,10 @@ jobs:
         if: success() || failure()
         run: pytest --cov=src --cov-report=lcov
 
+      - name: Check quickstart, including installation
+        if: success() || failure()
+        run: bash ./docs/source/quickstart/test_quickstart_example.sh
+
   coverage:
     runs-on: ubuntu-latest
     needs: [base_coverage, test]

docs/source/dependencies.rst

@@ -0,0 +1,23 @@
+
+Dependencies
+============
+
+Simple actions depend only on their input parameters and the :class:`~labthings_fastapi.thing.Thing` on which they are defined. However, it's quite common to need something else, for example accessing another :class:`~labthings_fastapi.thing.Thing` instance on the same LabThings server. There are two important principles to bear in mind here:
+
+* Other :class:`~labthings_fastapi.thing.Thing` instances should be accessed using a :class:`~labthings_fastapi.client.in_server.DirectThingClient` subclass if possible. This creates a wrapper object that should work like a :class:`~labthings_fastapi.client.ThingClient`, meaning your code should work either on the server or in a client script. This makes the code much easier to debug.
+* LabThings uses the FastAPI "dependency injection" mechanism, where you specify what's needed with type hints, and the argument is supplied automatically at run-time. You can see the `FastAPI documentation`_ for more information.
+
+LabThings provides a shortcut to create the annotated type needed to declare a dependency on another :class:`~labthings_fastapi.thing.Thing`, with the function :func:`~labthings_fastapi.dependencies.thing.direct_thing_client_dependency`. This generates a type annotation that you can use when you define your actions, that will supply a client object when the action is called. 
+
+:func:`~labthings_fastapi.dependencies.thing.direct_thing_client_dependency` takes a :func:`~labthings_fastapi.thing.Thing` class and a path as arguments: these should match the configuration of your LabThings server. Optionally, you can specify the actions that you're going to use. The default behaviour is to make all actions available, however it is more efficient to specify only the actions you will use.
+
+Dependencies are added recursively - so if you depend on another Thing, and some of its actions have their own dependencies, those dependencies are also added to your action. Using the ``actions`` argument means you only need the dependencies of the actions you are going to use, which is more efficient.
+
+.. literalinclude:: example.py
+    :language: python
+    
+In the example above, the :func:`increment_counter` action on :class:`TestThing` takes a :class:`MyThing` as an argument. When the action is called, the ``my_thing`` argument is supplied automatically. The argument is not the :class:`MyThing` instance, instead it is a wrapper class (a dynamically generated :class:`~labthings_fastapi.client.in_server.DirectThingClient` subclass). The wrapper should have the same signature as a :class:`~labthings_fastapi.client.ThingClient`. This means any dependencies of actions on the :class:`MyThing` are automatically supplied, so you only need to worry about the arguments that are not dependencies. The aim of this is to ensure that the code you write for your :class:`Thing` is as similar as possible to the code you'd write if you were using it through the Python client module.
+
+If you need access to the actual Python object (e.g. you need to access methods that are not decorated as actions), you can use the :func:`~labthings_fastapi.dependencies.raw_thing.raw_thing_dependency` function instead. This will give you the actual Python object, but you will need to supply all the arguments of the actions, including dependencies, yourself.
+
+.. _`FastAPI documentation`: https://fastapi.tiangolo.com/tutorial/dependencies/

docs/source/dependencies/dependencies.rst

@@ -0,0 +1,26 @@
+from labthings_fastapi.thing import Thing
+from labthings_fastapi.decorators import thing_action
+from labthings_fastapi.dependencies.thing import direct_thing_client_dependency
+from labthings_fastapi.example_things import MyThing
+from labthings_fastapi.server import ThingServer
+
+MyThingDep = direct_thing_client_dependency(MyThing, "/mything/")
+
+
+class TestThing(Thing):
+    """A test thing with a counter property and a couple of actions"""
+
+    @thing_action
+    def increment_counter(self, my_thing: MyThingDep) -> None:
+        """Increment the counter on another thing"""
+        my_thing.increment_counter()
+
+
+server = ThingServer()
+server.add_thing(MyThing(), "/mything/")
+server.add_thing(TestThing(), "/testthing/")
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(server.app, port=5000)

docs/source/dependencies/example.py

@@ -11,8 +11,8 @@ Welcome to labthings-fastapi's documentation!
    :caption: Contents:
 
    core_concepts.rst
-   quickstart.rst
-   dependencies.rst
+   quickstart/quickstart.rst
+   dependencies/dependencies.rst
 
    apidocs/index
 

docs/source/index.rst

@@ -0,0 +1,42 @@
+import time
+from labthings_fastapi.thing import Thing
+from labthings_fastapi.decorators import thing_action
+from labthings_fastapi.descriptors import PropertyDescriptor
+
+
+class TestThing(Thing):
+    """A test thing with a counter property and a couple of actions"""
+
+    @thing_action
+    def increment_counter(self) -> None:
+        """Increment the counter property
+
+        This action doesn't do very much - all it does, in fact,
+        is increment the counter (which may be read using the
+        `counter` property).
+        """
+        self.counter += 1
+
+    @thing_action
+    def slowly_increase_counter(self) -> None:
+        """Increment the counter slowly over a minute"""
+        for i in range(60):
+            time.sleep(1)
+            self.increment_counter()
+
+    counter = PropertyDescriptor(
+        model=int, initial_value=0, readonly=True, description="A pointless counter"
+    )
+
+
+if __name__ == "__main__":
+    from labthings_fastapi.server import ThingServer
+    import uvicorn
+
+    server = ThingServer()
+
+    # The line below creates a TestThing instance and adds it to the server
+    server.add_thing(TestThing(), "/counter/")
+
+    # We run the server using `uvicorn`:
+    uvicorn.run(server.app, port=5000)

docs/source/quickstart.rst

@@ -0,0 +1,11 @@
+from labthings_fastapi.client import ThingClient
+
+counter = ThingClient.from_url("http://localhost:5000/counter/")
+
+v = counter.counter
+print(f"The counter value was {v}")
+
+counter.increment_counter()
+
+v = counter.counter
+print(f"After incrementing, the counter value was {v}")

docs/source/quickstart/counter.py

@@ -0,0 +1,5 @@
+{
+    "things": {
+        "example": "labthings_fastapi.example_things:MyThing"
+    }
+}

docs/source/quickstart/counter_client.py

@@ -0,0 +1,52 @@
+Quick start
+===========
+
+You can install `labthings-fastapi` using `pip`. We recommend you create a virtual environment, for example:
+
+
+.. 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``:
+
+.. literalinclude:: counter.py
+    :language: python
+    
+``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:
+
+
+.. 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/.
+
+You can also interact with it from another Python instance, for example by running:
+
+.. literalinclude:: counter_client.py
+    :language: python
+
+It's best to write ``Thing`` subclasses in Python packages that can be imported. This makes them easier to re-use and distribute, and also allows us to run a LabThings server from the command line, configured by a configuration file. An example config file is below:
+
+.. literalinclude:: example_config.json
+    :language: JSON
+
+Paste this into ``example_config.json`` and then run a server using:
+
+.. code-block:: bash
+
+    labthings-server -c example_config.json
+
+Bear in mind that this won't work if `counter.py` above is still running - both will try to use port 5000. 
+
+As before, you can visit http://localhost:5000/docs or http://localhost:5000/example/ to see the OpenAPI docs or Thing Description, and you can use the Python client module with the second of those URLs.