Auto-generate docs

README.md

@@ -98,3 +98,7 @@ To run the tests you will need to:
 3. Execute `pip3 install -e .[docs]` in the project root folder.
 3. Go to `<project root folder>/docs` and execute `make html`. 
    Repeat this step to generate new docs.
+   
+To auto-generate the docs do `pip3 install -e .[docs-auto]`, then
+execute, in the root folder of the project 
+`sphinx-autobuild docs docs/_build/html`.

docs/devices.rst

@@ -1,16 +1,14 @@
-Inventory
+Devices
 #########
 
-Devicehub uses the same path to get devices and lots.
+You can retrieve devices using ``GET /devices/``, or a specific
+device by ``GET /devices/24``.
 
-To get all devices and groups: ``GET /inventory`` or the devices of a
+You can **filter** devices ``GET /devices/?filter={"type": "Computer"}``,
-specific groups: ``GET /inventory/24``.
+**sort** them ``GET /devices/?sort={"created": 1}``, and perform
-
+natural search with ``GET /devices/?search=foo bar. Of course
-You can **filter** devices ``GET /inventory/24?filter={"type": "Computer"}``,
+you can combine them in the same query, returning devices that
-and **sort** them ``GET /inventory?sort={"created": 1}``, and of course
+only pass all conditions.
-you can combine both in the same query. You only get the groups that
-contain the devices that pass the filters. So, if a group contains
-only one device that is filtered, you don't get that group neither.
 
 Results are **paginated**; you get up to 30 devices and up to 30
 groups in a page. Select the actual page by ``GET /inventory?page=3``.
@@ -21,21 +19,10 @@ Query
 The query consists of 4 optional params:
 
 - **search**: Filters devices by performing a full-text search over their
-  physical properties, events, tags, and groups they are in:
+  physical properties, events, and tags. Search is a string.
-
-    - Device.type
-    - Device.serial_number
-    - Device.model
-    - Device.manufacturer
-    - Device.color
-    - Tag.id
-    - Tag.org
-    - Group.name
-
-  Search is a string.
 - **filter**: Filters devices field-by-field. Each field can be
   filtered in different ways, see them in
-  :class:`ereuse_devicehub.resources.inventory.Filters`. Filter is
+  :class:`ereuse_devicehub.resources.devices.Filters`. Filter is
   a JSON-encoded object whose keys are the filters. By default
   is empty (no filter applied).
 - **sort**: Sorts the devices. You can specify multiple sort clauses

docs/index.rst

@@ -14,7 +14,7 @@ This is the documentation and API of the `eReuse.org Devicehub
 
     actions
     agents
-    inventory
+    devices
     tags
     lots
 

setup.py

@@ -50,6 +50,9 @@ setup(
             'sphinxcontrib-plantuml >= 0.12',
             'sphinxcontrib-websupport >= 1.0.1'
         ],
+        'docs-auto': [
+            'sphinx-autobuild'
+        ],
         'test': test_requires
     },
     tests_require=test_requires,