Update docs

docs/actions.rst

@@ -1,15 +1,14 @@
-Actions and states
-##################
-
 Actions
-*******
-
+#######
 Actions are events performed to devices, changing their **state**.
 Actions can have attributes defining
 **where** it happened, **who** performed them, **when**, etc.
 Actions are stored in a log for each device. An exemplifying action
 can be ``Repair``, which dictates that a device has been repaired,
-after this action, the device is in the ``repaired`` state.
+after this action, the device is in the ``repaired`` state. Another
+example is performing a ``Sell`` to agent 1 (now this agent *owns*
+the device), and then performing another ``Sell`` to agent 2 (now
+agent 2 is the owner).
 
 Devicehub actions inherit from `schema actions
 <http://schema.org/Action>`_, are written in Pascal case and using
@@ -19,14 +18,14 @@ is going to be / must be repaired, whereas ``Repair`` states
 that the reparation happened. The former actions have the preposition
 *To* prefixing the verb.
 
-Actions and states affect devices in different ways or **dimensions**.
+:ref:`actions:Actions` and :ref:`states:States` affect devices in
+different ways or **dimensions**.
 For example, ``Repair`` affects the **physical** dimension of a device,
 and ``Sell`` the **political** dimension of a device. A device
 can be in several states at the same time, one per dimension; ie. a
 device can be ``repaired`` (physical) and ``reserved`` (political),
 but not ``repaired`` and ``disposed`` at the same time:
 
-
 - Physical actions: The following actions describe and react on the
   Physical condition of the devices.
 
@@ -37,7 +36,7 @@ but not ``repaired`` and ``disposed`` at the same time:
   - DisposeWaste, Recover
 
 - Association actions: Actions that change the associations users have with devices;
-  ie. the **owners**, **usufructuarees**, **reservees**,
+  ie. the **owners**, **usufructuarees** (*from usufruct*), **reservees** (*from reserve*),
   and **physical possessors**.
 
   - Trade
@@ -60,15 +59,8 @@ but not ``repaired`` and ``disposed`` at the same time:
 The following index has all the actions (please note we are moving from calling them
 ``Event`` to call them ``Action``):
 
+Schema
+******
+
 .. dhlist::
     :module: ereuse_devicehub.resources.event.schemas
-
-
-States
-******
-.. autoclass:: ereuse_devicehub.resources.device.states.State
-
-.. uml:: states.puml
-
-.. autoclass:: ereuse_devicehub.resources.device.states.Trading
-.. autoclass:: ereuse_devicehub.resources.device.states.Physical

docs/devices.rst

@@ -1,6 +1,19 @@
 Devices
-#########
+#######
+Devices are objects that can be identified, and they are the
+main entity in a Devicehub. Refer to :ref:`devices:Device` for more
+info.
 
+Schema
+******
+The following schema represents all the device types and their
+properties.
+
+.. dhlist::
+    :module: ereuse_devicehub.resources.device.schemas
+
+API
+***
 You can retrieve devices using ``GET /devices/``, or a specific
 device by ``GET /devices/24``.
 
@@ -46,5 +59,4 @@ The result is a JSON object with the following fields:
   - **next**: The number of the next page, if any.
   - **last**: The number of the last page, if any.
 
-.. dhlist::
-    :module: ereuse_devicehub.resources.device.schemas
+

docs/index.rst

@@ -14,19 +14,36 @@ reusing devices, created under the project
 
 Our main objectives are:
 
-- To offer a common IT Asset Management for donors, receivers and IT
-  professionals so they can manage devices and exchange them.
-  This is, reusing –and ultimately recycling.
+- To offer a common IT Asset Management for distributors, refurbishers,
+  receivers and other IT professionals so they can manage devices and exchange them.
+  This is, reusing —and ultimately recycling.
 - To automatically recollect, analyse, process and share
   (controlling privacy) metadata about devices with other tools of the
   eReuse ecosystem to guarantee traceability, and to provide inputs for
   the indicators which measure circularity.
-- To highly integrate with existing IT Asset Management Systems.
-- To be decentralized.
 
-Devicehub is built with `Teal <https://github.com/bustawin/teal>`_ and
-`Flask <http://flask.pocoo.org>`_.
+The main entity of a Devicehub are :ref:`devices:Devices`, which is any object that
+can be identified. Devices are divided in *types* (like ``Computer``),
+and each one defines *properties*, like serial number, weight,
+quality rating, pricing, or a list of owners.
 
+We perform :ref:`actions:Actions` on devices, which are events that
+change their *state* and *properties*. Examples are sales, reparations,
+quality diagnostics, data wiping, and location.
+Actions are stored in the traceability log of the device.
+
+Devicehub is decentralized, and each instance is an inventory. We can
+share and exchange devices between inventories —like in real live between
+organizations.
+
+:ref:`tags:Tags` identify devices through those organizations and their
+internal systems. With Devicehub we can manage and print smart tags with
+QR and NFC capabilities, operating devices by literally scanning them.
+
+Devicehub is a REST API built with `Teal <https://github.com/ereuse/teal>`_ and
+`Flask <http://flask.pocoo.org>`_ using `PostgreSQL <https://www.postgresql.org>`_.
+`DevicehubClient <https://github.com/ereuse/devicehubclient>`_ is the
+front–end that consumes this API.
 
 ..  toctree::
     :maxdepth: 2
@@ -34,6 +51,7 @@ Devicehub is built with `Teal <https://github.com/bustawin/teal>`_ and
     api
     devices
     actions
+    states
     tags
     lots
 

docs/states.rst

@@ -0,0 +1,48 @@
+States
+######
+.. note:: In construction.
+
+A mutable property of a device result of applying an
+:ref:`actions:Action` to it.
+
+States are represented as properties in :ref:`devices:Device` and
+sub–types. They can be steps in a workflow
+(like ``sold`` and ``payed``, part of a trading), or properties
+describing computed values from applying events (like a list of owners,
+or a quality rating).
+
+There are three types of states:
+
+* **Trading**: a workflow of states resulting from applying the action
+  :ref:`actions:Trade`.
+* **Physical**: a workflow of states resulting from applying
+  physical actions (ref. :ref:`actions:Actions`).
+* **Attributes**: miscellaneous device properties that are not part of
+  a workflow.
+
+.. uml:: states.puml
+
+Trading
+*******
+ Trading states.
+
+:cvar Reserved: The device has been reserved.
+:cvar Cancelled: The device has been cancelled.
+:cvar Sold: The device has been sold.
+:cvar Donated: The device is donated.
+:cvar Renting: The device is in renting
+:cvar ToBeDisposed: The device is disposed.
+      This is the end of life of a device.
+:cvar ProductDisposed: The device has been removed
+      from the facility. It does not mean end-of-life.
+
+Physical
+********
+ Physical states.
+
+:cvar ToBeRepaired: The device has been selected for reparation.
+:cvar Repaired: The device has been repaired.
+:cvar Preparing: The device is going to be or being prepared.
+:cvar Prepared: The device has been prepared.
+:cvar ReadyToBeUsed: The device is in working conditions.
+:cvar InUse: The device is being reported to be in active use.

ereuse_devicehub/resources/device/states.py

@@ -6,6 +6,10 @@ from ereuse_devicehub.resources.event import models as e
 
 
 class State(Enum):
+    """A mutable property of a device result of applying an
+    :ref:`actions:Action` to it.
+    """
+
     @classmethod
     def events(cls):
         """Events participating in this state."""