Updated documentation

Author: Joel Collins

docs/advanced_usage/components.rst

@@ -0,0 +1,4 @@
+Components
+==========
+
+*Documentation to be written*

docs/advanced_usage/encoders.rst

@@ -0,0 +1,4 @@
+Data encoders
+=============
+
+*Documentation to be written*

docs/advanced_usage/extensions.rst

@@ -0,0 +1,4 @@
+LabThing Extensions
+===================
+
+*Documentation to be written*

docs/advanced_usage/index.rst

@@ -0,0 +1,11 @@
+Advanced usage
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   view_class.rst
+   components.rst
+   encoders.rst
+   extensions.rst

docs/advanced_usage/view_class.rst

@@ -0,0 +1,13 @@
+View classes
+============
+
+*Documentation to be written*
+
+Base View
+---------
+
+Property View
+-------------
+
+Action View
+-----------

docs/basic_usage/action_tasks.rst renamed to docs/basic_usage/action_threads.rst

@@ -1,23 +1,24 @@
-Action tasks
-============
+Action threads
+==============
 
 Many actions in your LabThing may perform tasks that take a long time (compared to the expected response time of a web request). For example, if you were to implement a timelapse action, this inherently runs over a long time.
 
 This introduces a couple of problems. Firstly, a request that triggers a long function will, by default, block the Python interpreter for the duration of the function. This usually causes the connection to timeout, and the response will never be revieved.
 
-Tasks are introduced to manage long-running functions in a way that does not block HTTP requests. Any API Action will automatically run as a task.
+Tasks are introduced to manage long-running functions in a way that does not block HTTP requests. Any API Action will automatically run as a background thread.
 
-Internally, the :class:`labthings.LabThing` object stores a list of all requested actions, and their states. This state stores the running status of the action (if itis idle, running, error, or success), information about the start and end times, a unique task ID, and, upon completion, the return value of the long-running function. 
+Internally, the :class:`labthings.LabThing` object stores a list of all requested actions, and their states. This state stores the running status of the action (if itis idle, running, error, or success), information about the start and end times, a unique ID, and, upon completion, the return value of the long-running function. 
 
-By using  tasks, a function can be started in the background, and it's return value fetched at a later time once it has reported success. If a long-running action is started by some client, it should note the ID returned in the action state JSON, and use this to periodically check on the status of that particular action. 
+By using threads, a function can be started in the background, and it's return value fetched at a later time once it has reported success. If a long-running action is started by some client, it should note the ID returned in the action state JSON, and use this to periodically check on the status of that particular action. 
 
-API routes have been created to allow checking the state of all actions (GET ``/actions``), a particular task by ID (GET ``/actions/<action_id>``), and terminating or removing individual tasks (DELETE ``/actions/<action_id>``).
+API routes have been created to allow checking the state of all actions (GET ``/actions``), a particular action by ID (GET ``/actions/<action_id>``), and terminating or removing individual actions (DELETE ``/actions/<action_id>``).
 
-All Actions will return a serialized representation of the task, when your POST request returns. If the task completes within a default timeout period (usually 1 second) then the completed Action representation will be returned. If the task is still running after this timeout period, the "in-progress" Action representation will be returned. The final output value can then be retrieved at a later time.
+All actions will return a serialized representation of the action state when your POST request returns. If the action completes within a default timeout period (usually 1 second) then the completed action representation will be returned. If the action is still running after this timeout period, the "in-progress" action representation will be returned. The final output value can then be retrieved at a later time.
 
 Most users will not need to create instances of this class. Instead, they will be created automatically when a function is started by an API Action view.
 
 .. autoclass:: labthings.actions.ActionThread
+   :noindex:
    :members:
 
 Accessing the current action thread
@@ -34,7 +35,7 @@ Updating action progress
 
 Some client applications may be able to display progress bars showing the progress of an action. Implementing progress updates in your actions is made easy with the :py:meth:`labthings.update_action_progress` function. This function takes a single argument, which is the action progress as an integer percent (0 - 100).
 
-If your long running function was started within a background task, this function will update the state of the corresponding action object. If your function is called outside of a long-running task (e.g. by some internal code, not the web API), then this function will silently do nothing.
+If your long running function was started within a :class:`labthings.actions.ActionThread`, this function will update the state of the corresponding :class:`labthings.actions.ActionThread` instance. If your function is called outside of an :class:`labthings.actions.ActionThread` (e.g. by some internal code, not the web API), then this function will silently do nothing.
 
 .. autofunction:: labthings.update_action_progress
-   :noindex:
+   :noindex:

docs/basic_usage/index.rst

@@ -7,7 +7,7 @@ Basic usage
 
    app_thing_server.rst
    http_api_structure.rst
-   websocket_api_structure.rst
+   ws_api_structure.rst
    serialising.rst
-   action_tasks.rst
+   action_threads.rst
    synchronisation.rst

docs/index.rst

@@ -9,6 +9,7 @@ Welcome to Python-LabThings' documentation!
    quickstart.rst
 
    basic_usage/index.rst
+   advanced_usage/index.rst
 
    api.rst
 

src/labthings/actions/pool.py

@@ -123,7 +123,7 @@ def current_action():
     If this function is called from outside an ActionThread, it will return None.
 
 
-    :returns: ActionThread -- Currently running ActionThread.
+    :returns: :class:`labthings.actions.ActionThread` -- Currently running ActionThread.
 
     """
     current_action_thread = threading.current_thread()
@@ -133,12 +133,11 @@ def current_action():
 
 
 def update_action_progress(progress: int):
-    """Update the progress of the Task in which the caller is currently running.
+    """Update the progress of the ActionThread in which the caller is currently running.
     
-    If this function is called from outside a Task thread, it will do nothing.
+    If this function is called from outside an ActionThread, it will do nothing.
 
-    :param progress: int
-    :param progress: int: 
+    :param progress: int: Action progress, in percent (0-100)
 
     """
     if current_action():
@@ -148,12 +147,11 @@ def update_action_progress(progress: int):
 
 
 def update_action_data(data: dict):
-    """Update the data of the Task in which the caller is currently running.
+    """Update the data of the ActionThread in which the caller is currently running.
     
-    If this function is called from outside a Task thread, it will do nothing.
+    If this function is called from outside an ActionThread, it will do nothing.
 
-    :param data: dict
-    :param data: dict: 
+    :param data: dict: Action data dictionary
 
     """
     if current_action():

src/labthings/actions/thread.py

@@ -110,7 +110,9 @@ def status(self):
 
     @property
     def dead(self):
-        """ """
+        """
+        Has the thread finished, by any means (return, exception, termination).
+        """
         return not self.is_alive()
 
     @property
@@ -120,8 +122,9 @@ def stopped(self):
 
     def update_progress(self, progress: int):
         """
+        Update the progress of the ActionThread.
 
-        :param progress: int: 
+        :param progress: int: Action progress, in percent (0-100)
 
         """
         # Update progress of the task