diff --git a/README.md b/README.md index 3e1d53bd..ff281f8b 100644 --- a/README.md +++ b/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 `/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`. diff --git a/docs/inventory.rst b/docs/devices.rst similarity index 61% rename from docs/inventory.rst rename to docs/devices.rst index 9697bcc1..4403b992 100644 --- a/docs/inventory.rst +++ b/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 -specific groups: ``GET /inventory/24``. - -You can **filter** devices ``GET /inventory/24?filter={"type": "Computer"}``, -and **sort** them ``GET /inventory?sort={"created": 1}``, and of course -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. +You can **filter** devices ``GET /devices/?filter={"type": "Computer"}``, +**sort** them ``GET /devices/?sort={"created": 1}``, and perform +natural search with ``GET /devices/?search=foo bar. Of course +you can combine them in the same query, returning devices that +only pass all conditions. 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: - - - Device.type - - Device.serial_number - - Device.model - - Device.manufacturer - - Device.color - - Tag.id - - Tag.org - - Group.name - - Search is a string. + physical properties, events, and tags. 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 diff --git a/docs/index.rst b/docs/index.rst index d263fb8b..b3b6cac7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ This is the documentation and API of the `eReuse.org Devicehub actions agents - inventory + devices tags lots diff --git a/setup.py b/setup.py index cc726397..802a6f8b 100644 --- a/setup.py +++ b/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,