pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some more documentation

Browse source
This commit is contained in:
Gina Häußge 2016-09-22 22:21:52 +02:00
parent 9845e3b4ea
commit 0b551f6b7e
11 changed files with 275 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
docs/api/fileops.rst → docs/api/files.rst
View file

2
docs/api/index.rst
View file

@ -11,7 +11,7 @@ REST API
version.rst
apps.rst
connection.rst
fileops.rst
files.rst
job.rst
languages.rst
logs.rst

225
docs/api/languages.rst
View file

@ -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 <sec-api-languages-datamodel-listresponse>`.
**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 <sec-api-languages-list>`.
: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 <sec-api-languages-list>`.
**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 <sec-api-languages-datamodel-componentlist>`
- 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 <sec-api-languages-datamodel-packmeta>`
- 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

13
docs/api/timelapse.rst
View file

@ -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 <sec-api-timelapse-datamodel-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 <sec-api-timelapse-datamodel-config>` to use for the next print.
The configuration is expected as the request body.
Requires user rights.
.. _sec-api-timelapse-datamodel:
Data model

11
docs/api/util.rst
View file

@ -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

2
docs/api/wizard.rst
View file

@ -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

9
docs/jsclientlib/languages.rst
View file

@ -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 <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. seealso::
:ref:`Languages API <sec-api-languages>`
The documentation of the underlying languages API.

5
docs/jsclientlib/settings.rst
View file

@ -34,3 +34,8 @@
:param object settings: The settings to save
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. seealso::
:ref:`Settings API <sec-api-settings>`
The documentation of the underlying settings API.

5
docs/jsclientlib/timelapse.rst
View file

@ -22,3 +22,8 @@
.. js:function:: getConfig(opts)
.. js:function:: saveConfig(config, opts)
.. seealso::
:ref:`Timelapse API <sec-api-timelapse>`
The documentation of the underlying timelapse API.

5
docs/jsclientlib/users.rst
View file

@ -26,3 +26,8 @@
.. js:function:: OctoPrint.users.getSettings(name, opts)
.. js:function:: OctoPrint.users.saveSettings(name, settings, opts)
.. seealso::
:ref:`User API <sec-api-users>`
The documentation of the underlying user API.

2
src/octoprint/server/api/languages.py
View file

@ -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")