From 0b551f6b7e4dcd4d617f581592610a93ef4dc61e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Thu, 22 Sep 2016 22:21:52 +0200 Subject: [PATCH] Some more documentation --- docs/api/{fileops.rst => files.rst} | 0 docs/api/index.rst | 2 +- docs/api/languages.rst | 225 +++++++++++++++++++++++++- docs/api/timelapse.rst | 13 ++ docs/api/util.rst | 11 ++ docs/api/wizard.rst | 2 + docs/jsclientlib/languages.rst | 9 ++ docs/jsclientlib/settings.rst | 5 + docs/jsclientlib/timelapse.rst | 5 + docs/jsclientlib/users.rst | 5 + src/octoprint/server/api/languages.py | 2 +- 11 files changed, 275 insertions(+), 4 deletions(-) rename docs/api/{fileops.rst => files.rst} (100%) diff --git a/docs/api/fileops.rst b/docs/api/files.rst similarity index 100% rename from docs/api/fileops.rst rename to docs/api/files.rst diff --git a/docs/api/index.rst b/docs/api/index.rst index 6347254e..6eb090eb 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,7 +11,7 @@ REST API version.rst apps.rst connection.rst - fileops.rst + files.rst job.rst languages.rst logs.rst diff --git a/docs/api/languages.rst b/docs/api/languages.rst index f1aede21..ac7b988f 100644 --- a/docs/api/languages.rst +++ b/docs/api/languages.rst @@ -4,8 +4,229 @@ Languages ********* -.. todo:: +.. note:: - Needs to be documented + All language pack management operations require admin rights. .. contents:: + +.. _sec-api-languages-list: + +Retrieve installed language packs +================================= + +.. http:get:: /api/languages + + Retrieves a list of installed language packs. + + The response body will contain a :ref:`list response `. + + **Example** + + .. sourcecode:: http + + GET /api/languages HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "language_packs": { + "_core": { + "identifier": "_core", + "name": "Core", + "languages": [ + ... + ] + }, + "some_plugin": { + "identifier": "some_plugin", + "name": "Some Plugin", + "languages": [ + { + "locale": "de", + "locale_display": "Deutsch", + "locale_english": "German", + "last_update": 1474574597, + "author": "Gina Häußge" + }, + { + "locale": "it", + "locale_display": "Italiano", + "locale_english": "Italian", + "last_update": 1470859680, + "author": "The italian Transifex Team" + } + ... + ] + } + } + + :statuscode 200: No error + +.. _sec-api-languages-upload: + +Upload a language pack +====================== + +.. http:post:: /api/languages + + Uploads a new language pack to OctoPrint. + + Other than most of the other requests on OctoPrint's API which are expected as JSON, this request is expected as + ``Content-Type: multipart/form-data`` due to the included file upload. + + To upload a file, the request body must contain the ``file`` form field with the + contents and file name of the file to upload. + + Only files with one of the extensions ``zip``, ``tar.gz``, ``tgz`` or ``tar`` will be + processed, for other file extensions a :http:statuscode:`400` will be returned. + + Will return a list of installed language packs upon completion, as described in + :ref:`Retrieve installed language packs `. + + :form file: The language pack file to upload + :statuscode 200: The file was uploaded successfully + +.. _sec-api-languages-delete: + +Delete a language pack +====================== + +.. http:delete:: /api/languages/(string:locale)/(string:pack) + + Deletes the language pack ``pack`` for locale ``locale``. Can be either + the ``_core`` pack (containing translations for core OctoPrint) or + the language pack for a plugin specified by the plugin identifier. + + Returns a list of installed language packs, as described in + :ref:`Retrieve installed language packs `. + + **Example** + + .. sourcecode:: http + + DELETE /api/languages/it/some_plugin HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "language_packs": { + "_core": { + "identifier": "_core", + "name": "Core", + "languages": [ + ... + ] + }, + "some_plugin": { + "identifier": "some_plugin", + "name": "Some Plugin", + "languages": [ + { + "locale": "de", + "locale_display": "Deutsch", + "locale_english": "German", + "last_update": 1474574597, + "author": "Gina Häußge" + }, + ... + ] + } + } + + :param locale: The locale for which to delete the language pack + :param pack: The language pack to delete + :statuscode 200: The language pack was deleted + +.. _sec-api-languages-datamodel: + +Data model +========== + +.. _sec-api-languages-datamodel-listresponse: + +List response +------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``language_packs`` + - 0..* + - Map of :ref:`component lists ` + - Map of component lists, indexed by the component's identifier + +.. _sec-api-languages-datamodel-componentlist: + +Component list +-------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``identifier`` + - 1 + - string + - The plugin's identifier, ``_core`` for core OctoPrint, the plugin's identifier for plugins + * - ``display`` + - 1 + - string + - Displayable name of the component, ``Core`` for core OctoPrint, the plugin's name for plugins + * - ``languages`` + - 0..* + - List of :ref:`language pack meta data ` + - Language packs for the component + +.. _sec-api-languages-datamodel-packmeta: + +Language pack metadata +---------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``locale`` + - 1 + - string + - Locale of the language pack + * - ``locale_display`` + - 1 + - string + - Displayable name of the locale + * - ``locale_english`` + - 1 + - string + - English representation of the locale + * - ``last_update`` + - 0..1 + - int + - Timestamp of the last update of the language pack + * - ``author`` + - 0..1 + - string + - Author of the language pack diff --git a/docs/api/timelapse.rst b/docs/api/timelapse.rst index ea9d5f36..914e4349 100644 --- a/docs/api/timelapse.rst +++ b/docs/api/timelapse.rst @@ -13,6 +13,13 @@ Retrieve a list of timelapses and the current config .. http:get:: /api/timelapse + Retrieves a list of timelapses and the current config. + + Returns a :ref:`timelapse list ` in the + response body. + + :param unrendered: If provided and true, also include unrendered timelapses + .. _sec-api-timelapse-delete: Delete a timelapse @@ -36,6 +43,8 @@ Issue a command for an unrendered timelapse Requires user rights. + :json command: The command to issue, currently only ``render`` is supported + .. _sec-api-timelapse-delete-unrendered: Delete an unrendered timelapse @@ -56,6 +65,10 @@ Change current timelapse config Save a new :ref:`timelapse configuration ` to use for the next print. + The configuration is expected as the request body. + + Requires user rights. + .. _sec-api-timelapse-datamodel: Data model diff --git a/docs/api/util.rst b/docs/api/util.rst index 6654d5e2..3c3a8d0f 100644 --- a/docs/api/util.rst +++ b/docs/api/util.rst @@ -224,6 +224,17 @@ Test paths or URLs } } + :json command: The command to execute, currently either ``path`` or ``url`` + :json path: ``path`` command only: the path to test + :json check_type: ``path`` command only: the type of path to test for, either ``file`` or ``dir`` + :json check_access: ``path`` command only: a list of access permissions to check for + :json url: ``url`` command only: the URL to test + :json status: ``url`` command only: one or more expected status codes + :json method: ``url`` command only: the HTTP method to use for the check + :json timeout: ``url`` command only: the timeout for the HTTP request + :json response: ``url`` command only: whether to include response data and if so in what form + :statuscode 200: No error occurred + .. _sec-api-util-datamodel: Data model diff --git a/docs/api/wizard.rst b/docs/api/wizard.rst index 96a45f00..dfbb1380 100644 --- a/docs/api/wizard.rst +++ b/docs/api/wizard.rst @@ -37,6 +37,8 @@ Finish wizards supplying the information whether the wizard plugin's identifier was within the list of ``handled`` wizards or not. + :json handled: A list of handled wizards + .. _sec-api-wizard-datamodel: Data model diff --git a/docs/jsclientlib/languages.rst b/docs/jsclientlib/languages.rst index c2737589..5eae2015 100644 --- a/docs/jsclientlib/languages.rst +++ b/docs/jsclientlib/languages.rst @@ -3,6 +3,11 @@ :mod:`OctoPrint.languages` -------------------------- +.. note:: + + All methods here require that the used API token or a the existing browser session + has admin rights. + .. js:function:: OctoPrint.languages.list(opts) Retrieves a list of available language packs. @@ -26,3 +31,7 @@ :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response +.. seealso:: + + :ref:`Languages API ` + The documentation of the underlying languages API. diff --git a/docs/jsclientlib/settings.rst b/docs/jsclientlib/settings.rst index 825d43ec..25a6aeb6 100644 --- a/docs/jsclientlib/settings.rst +++ b/docs/jsclientlib/settings.rst @@ -34,3 +34,8 @@ :param object settings: The settings to save :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response + +.. seealso:: + + :ref:`Settings API ` + The documentation of the underlying settings API. diff --git a/docs/jsclientlib/timelapse.rst b/docs/jsclientlib/timelapse.rst index 8862f66e..4fdbdbe5 100644 --- a/docs/jsclientlib/timelapse.rst +++ b/docs/jsclientlib/timelapse.rst @@ -22,3 +22,8 @@ .. js:function:: getConfig(opts) .. js:function:: saveConfig(config, opts) + +.. seealso:: + + :ref:`Timelapse API ` + The documentation of the underlying timelapse API. diff --git a/docs/jsclientlib/users.rst b/docs/jsclientlib/users.rst index 3b06440c..70487563 100644 --- a/docs/jsclientlib/users.rst +++ b/docs/jsclientlib/users.rst @@ -26,3 +26,8 @@ .. js:function:: OctoPrint.users.getSettings(name, opts) .. js:function:: OctoPrint.users.saveSettings(name, settings, opts) + +.. seealso:: + + :ref:`User API ` + The documentation of the underlying user API. diff --git a/src/octoprint/server/api/languages.py b/src/octoprint/server/api/languages.py index 19ae5ce4..e0749658 100644 --- a/src/octoprint/server/api/languages.py +++ b/src/octoprint/server/api/languages.py @@ -101,7 +101,7 @@ def uploadLanguagePack(): exts = filter(lambda x: upload_name.lower().endswith(x), (".zip", ".tar.gz", ".tgz", ".tar")) if not len(exts): - return make_response("File doesn't have a valid extension for a plugin archive", 400) + return make_response("File doesn't have a valid extension for a language pack archive", 400) target_path = settings().getBaseFolder("translations")