Added basic docs

Author: jtc42

docs/basic_usage/index.rst

@@ -0,0 +1,111 @@
+Basic usage
+===========
+
+The easiest way to get started with Python-LabThings is via the :mod:`labthings.quick` module, and the :class:`labthings.LabThing` builder methods.
+
+We will assume that for basic usage you already have some basic instrument control code. In our example, this is in the form of a ``PretendSpectrometer`` class, which will generate some data like your instrument control code might. Our ``PretendSpectrometer`` class has a ``data`` property which quickly returns a spectrum, an ``x_range`` property which determines the range of data we'll return, a ``magic_denoise`` property for cleaning up our signal, and a slow ``average_data(n)`` method to average ``n`` individual data measurements.
+
+Building an API from this class requires a few extra considerations. In order to tell our API what data to expect from users, we need to construct a schema for each of our interactions. This schema simply maps variable names to JSON-compatible types, and is made simple via the :mod:`labthings.fields` module. 
+
+For properties, the input and output MUST be formatted the same, and so a single ``schema`` argument handles both. For actions, the input parameters and output response may be different. In this case, we can pass a ``schema`` argument to format the output, and an ``args`` argument to specify the input parameters,
+
+An example Lab Thing built from our ``PretendSpectrometer`` class, complete with schemas, might look like:
+
+
+.. code-block:: python
+
+    from labthings.server.quick import create_app
+    from labthings.server import fields
+
+    from my_components import PretendSpectrometer
+
+
+    # Create LabThings Flask app
+    app, labthing = create_app(
+        __name__,
+        title="My PretendSpectrometer API",
+        description="LabThing API for PretendSpectrometer",
+        version="0.1.0"
+    )
+
+
+    # Make some properties and actions out of our component
+
+    # Single-shot data property
+    labthing.build_property(
+        my_component,  # Python object
+        "data",  # Objects attribute name
+        "/data",  # URL to bind the property to
+        description="A single-shot measurement",
+        readonly=True,
+        schema=fields.List(fields.Number())
+    )
+
+    # Magic denoise property
+    labthing.build_property(
+        my_component,  # Python object
+        "magic_denoise",  # Objects attribute name
+        "/denoise",  # URL to bind the property to
+        description="A magic denoise property",
+        schema=fields.Int(min=100, max=500, example=200)
+    )
+
+    # Averaged measurement action
+    labthing.build_action(
+        my_component.average_data,  # Python function
+        "/average",  # URL to bind the action to
+        description="Take an averaged measurement",
+        args={  # How do we convert from the request input to function arguments?
+            "n": fields.Int(description="Number of averages to take", example=5, default=5)
+        },
+    )
+
+
+    # Start the app
+    if __name__ == "__main__":
+        from labthings.server.wsgi import Server
+        Server(app).run()
+
+
+
+For completeness of the examples, our ``PretendSpectrometer`` class code is:
+
+.. code-block:: python
+
+    import random
+    import math
+    import time
+
+    class PretendSpectrometer:
+        def __init__(self):
+            self.x_range = range(-100, 100)
+            self.magic_denoise = 200
+
+        def make_spectrum(self, x, mu=0.0, sigma=25.0):
+            """
+            Generate a noisy gaussian function (to act as some pretend data)
+            
+            Our noise is inversely proportional to self.magic_denoise
+            """
+            x = float(x - mu) / sigma
+            return (
+                math.exp(-x * x / 2.0) / math.sqrt(2.0 * math.pi) / sigma
+                + (1 / self.magic_denoise) * random.random()
+            )
+
+        @property
+        def data(self):
+            """Return a 1D data trace."""
+            return [self.make_spectrum(x) for x in self.x_range]
+
+        def average_data(self, n: int):
+            """Average n-sets of data. Emulates a measurement that may take a while."""
+            summed_data = self.data
+
+            for _ in range(n):
+                summed_data = [summed_data[i] + el for i, el in enumerate(self.data)]
+                time.sleep(0.25)
+
+            summed_data = [i / n for i in summed_data]
+
+            return summed_data

docs/core_concepts.rst

@@ -0,0 +1,36 @@
+Core Concepts
+=============
+
+LabThings is rooted in the `W3C Web of Things standards <https://www.w3.org/WoT/>`_. Using IP networking in labs is not itself new, though perhaps under-used. However lack of proper standardisation has stiffled widespread adoption. LabThings, rather than try to introduce new competing standards, uses the architecture and terminology introduced by the W3C Web of Things. A full description of the core architecture can be found in the `Web of Things (WoT) Architecture <https://www.w3.org/TR/wot-architecture/#sec-wot-architecture>`_ document. However, a brief outline of core terminology is given below.
+
+Web Thing
+---------
+
+A Web Thing is defined as "an abstraction of a physical or a virtual entity whose metadata and interfaces are described by a WoT Thing description." For LabThings this corresponds to an individual lab instrument that exposes functionality available to the user via a web API, and that functionality is described by a Thing Description.
+
+LabThings automatically generates a Thing Description as you add functionality. The functionality you add falls into one of three categories of "interaction affordance": Properties, Actions, and Events.
+
+Properties
+----------
+
+A Property is defined as "an Interaction Affordance that exposes the state of the Thing. The state exposed by a Property MUST be retrievable (readable). Optionally, the state exposed by a Property MAY be updated (writeable)."
+
+As a rule of thumb, any attribute of your device that can be quickly read, or optionally written, should be a Property. For example, simple device settings, or one-shot measurements such as temperature.
+
+Actions
+-------
+
+An Action is defined as "an Interaction Affordance that allows to invoke a function of the Thing. An Action MAY manipulate state that is not directly exposed (cf. Properties), manipulate multiple Properties at a time, or manipulate Properties based on internal logic (e.g., toggle). Invoking an Action MAY also trigger a process on the Thing that manipulates state (including physical state through actuators) over time."
+
+The key point here is that Actions are typically more complex in functionality than simply setting or getting a property. For example, they can set multiple properties simultaneously (for example, auto-exposing a camera), or they can manipulate the state of the Thing over time, for example starting a long-running data acquisition.
+
+Python-LabThings automatically handles offloading Actions into background threads where appropriate. The Action has a short timeout to complete quickly and respond to the API request, after which time a ``201 - Started`` response is sent to the client with information on how to check the state of the Action at a later time. This is particularly useful for long-running data acquisitions, as it allows users to start an acquisition and get immediate confirmation that it has started, after which point they can poll for changes in status.
+
+Events
+------
+
+An event "describes an event source that pushes data asynchronously from the Thing to the Consumer. Here not state, but state transitions (i.e., events) are communicated. Events MAY be triggered through conditions that are not exposed as Properties."
+
+Common examples are notifying clients when a Property is changed, or when an Action starts or finishes. However, Thing developers can introduce new Events such as warnings, status messages, and logs. For example, a device may emit an events when the internal temperature gets too high, or when an interlock is tripped. This Event can then be pushed to both users AND other Things, allowing automtic response to external conditions.
+
+A good example of this might be having Things automatically pause data-acquisition Actions upon detection of an overheat or interlock Event from another Thing.

docs/index.rst

@@ -1,12 +1,14 @@
 Welcome to Python-LabThings' documentation!
-=======================================================
+===========================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-Indices and tables
-==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   basic_usage/index.rst
+
+
+Installation
+------------
+
+``pip install labthings``