Qtauto deployment server documentation updatev5.12.0_QtAS

Fixes: AUTOSUITE-625
Change-Id: I5433ce0c2af64109d3e4d3779d698f2c93eadb28
Reviewed-by: Svetlana Abramenkova <sabramenkova@luxoft.com>

1 files changed, 75 insertions, 66 deletions

diff --git a/doc/src/deployment-server.qdoc b/doc/src/deployment-server.qdoc
index c505c9b..1710ea4 100644
--- a/doc/src/deployment-server.qdoc
+++ b/doc/src/deployment-server.qdoc
@@ -28,34 +28,35 @@
 
 /*!
     \page qtauto-deployment-server-index.html
-    \title Qt Auto Deployment Server
-    \section1 Introduction
+    \title Qt Automotive Suite Deployment Server
     Qt Automotive Suite Deployment server is a reference implementation of a network resource for
     hosting and distributing applications in projects based on Qt Application Manager.
-    Even though the Deployment Server can be used in field for real products, the main purpose
+    Even though the deployment server can be used in the field for real products, the main purpose
     for it is helping development and integration teams to simplify development and testing of
     applications on target system.
+
+    When implementing the deployment server, certain assumptions were made.
     \section1 Assumptions
 
     \list
-        \li Applications are identified by a group of (Application ID, Version, Architecture, Tags).
+        \li Applications are identified by a group of: Application ID, version, architecture and tags.
         Such groups are unique.
-        \li Architecture is specified as a group of: (CPU architecture, endianness, bitness and OS).
-        If package does not contain architecture specific parts, architecture is specified as “All”.
+        \li Architecture is specified as a group of: CPU architecture, endianness, bitness and OS.
+        If a package does not contain architecture specific parts, the architecture is specified as \e{All}.
         \li CPU architecture is taken as returned by QsysInfo::buildCpuArchitecture().
-        \li As it is hard to determine OS for uploaded packages, OS-es are matched by binary format,
-        requesting anything unix-like will give packages with ELF binaries, anything Windows related
+        \li As it is hard to determine the OS for uploaded packages, they are matched by binary format.
+        Thus, requesting anything Unix-like will give packages with ELF binaries, anything Windows related
         will return packages with PE32 format binaries and packages with Mach_o binaries are returned
         for Apple products. See \l {http://doc.qt.io/qt-5/qsysinfo.html#kernelType} {QSysInfo::kernelType()} for more details.
-        \li When native and non-native applications match selection criteria, native application is preferred.
+        \li When native and non-native applications match selection criteria, the native application is preferred.
         \li Applications can be further filtered by tags, both as positive (must have) and negative
         (must not have) filters.
-        \li Tags are considered alphanumeric and can contain lowercase latin letters, numbers and
-        underscore symbol. All tags passed to the server are brought to lowercase.
-        \li Tags can optionally have version. Version is separated from tag by ':'. Version follows the same
-        limitations as tag.
+        \li Tags are considered alphanumeric and can contain lowercase Latin letters, numbers and
+        the underscore symbol. All tags passed to the server are converted to lowercase.
+        \li Tags can optionally have a version. The version number is separated from tag by a colon (:). The version follows the same
+        limitations as the tag.
         \li Tags are matched according to versions (when requesting version 5.12, it will match 5.12.0, but not vice versa).
-        Also, when requesting non-versioned tag - any version will match.
+        Also, when requesting a non-versioned tag - any version will match.
         \li Tag lists in requests and packages are simplified (so qt:5.12,qt:5.12.0 will end up as qt:5.12)
         \li \l {https://doc.qt.io/QtApplicationManager/manifest.html#basic-manifest} {Application manifest}
         allows for any number of categories assigned to application. Deployment server currently
@@ -63,35 +64,38 @@
         category to the application. This behavior can be discussed with nzamotaev@luxoft.com .
         \li Tag information is parsed from package header's \b{extra} and \b{extraSigned} parts,
         from \b{tags} array. All elements of that array are added to package’s tag list.
-        \li Every package has version. If manifest does not contain version,
-        it will be assigned version “0.0.0”.
+        \li Every package has a version number. If the manifest does not contain a version field,
+        the version number will be assigned “0.0.0”.
     \endlist
 
     \section1 API
     \section2 hello
-    Checks whether you are using the right Platform and the right API to communicate with the Server.
+    Checks whether you are using the correct Platform and the right API to communicate with the deployment server.
     \table
         \header
             \li Parameter
             \li Description
         \row
             \li platform
-            \li The platform the client is running on, this sets the architecture of the packages you get. (see \b{settings.APPSTORE_PLATFORM})
+            \li The platform the client is running on. This sets the architecture of the packages
+            you get (see \b{settings.APPSTORE_PLATFORM} parameter in \b{appstore/settings.py} file).
         \row
             \li version
-            \li The Deployment Server HTTP API version you are using to communicate with the server. (see \b{settings.APPSTORE_VERSION})
+            \li The Deployment Server HTTP API version you are using to communicate with the server
+            (see \b{settings.APPSTORE_VERSION}).
         \row
             \li require_tag
-            \li Optional parameter for filtering packages by tags. Receives comma-separated list of tags.
-            Only applications containing any of specified tags should be listed. Tags must be alphanumeric.
+            \li Optional parameter for filtering packages by tags. Receives a comma-separated list of tags.
+            Only applications containing any of the specified tags should be listed.
+            Tags must be alphanumeric.
         \row
             \li conflicts_tag
-            \li Optional parameter for filtering packages by tags. Receives comma-separated list of tags.
+            \li Optional parameter for filtering packages by tags. Receives a comma-separated list of tags.
             No application containing any of the tags should be listed. Tags must be alphanumeric.
         \row
             \li architecture
-            \li ptional parameter for filtering packages by architecture. Receives cpu architecture.
-            If architecture is not specified, only packages showing 'All' architecture are listed.
+            \li Optional parameter for filtering packages by architecture. Receives the CPU architecture.
+            If architecture is not specified, only packages showing \e{All} architecture are listed.
     \endtable
     Returns a JSON object:
     \table
@@ -108,17 +112,17 @@
             \li Server is in maintenance mode and can not be used at the moment.
         \row
             \li incompatible-platform
-            \li You are using incompatible platform.
+            \li You are using an incompatible platform.
         \row
             \li incompatible-version
-            \li You are using incompatible version of the API
+            \li You are using incompatible version of the API.
         \row
             \li malformed-tag
             \li Tag had wrong format, was not alphanumeric or could not be parsed.
     \endtable
     \section2 login
-    Does a login on the Server with the given username and password.
-    Either a IMEI or \l {https://en.wikipedia.org/wiki/MAC_address} {other unique hardware identifier} must be provided. This call is needed for downloading apps.
+    Logs onto the deployment server with the given username and password.
+    Either an IMEI or a \l {https://en.wikipedia.org/wiki/MAC_address} {unique hardware identifier} must be provided. This call is needed for downloading apps.
     \table
         \header
             \li Parameter
@@ -128,7 +132,7 @@
             \li The username
         \row
             \li password
-            \li Password for given username
+            \li Password for the given username
     \endtable
     Returns a JSON object:
     \table
@@ -142,16 +146,16 @@
             \li Login successful.
         \row
             \li missing-credentials
-            \li No username and/or password provided
+            \li No username or password provided
         \row
             \li account-disabled
-            \li Account is disabled in admin panel
+            \li Account is disabled in the admin panel
         \row
             \li authentication-failed
             \li Wrong username and/or password or other authentication error
     \endtable
     \section2 logout
-    Logs out currently logged in user on server.
+    Logs out the currently logged-in user from the deployment server.
 
     Returns a JSON object:
     \table
@@ -169,19 +173,19 @@
     \endtable
 
     \section2 app/list
-    Lists all apps. Returned List can be filtered by using the \b{category_id} and the \b{filter} arguments.
+    Lists all apps. The returned list can be filtered by using the \b{category_id} and the \b{filter} arguments.
     \table
         \header
             \li Parameter
             \li Description
         \row
             \li category_id
-            \li Limits applications to category with this id.
+            \li Limits applications to the category with this id.
         \row
             \li filter
-            \li Only lists apps, whose names match the filter.
+            \li Only lists apps whose names match the filter.
     \endtable
-    Returns a JSON array (\b{not an object!}). Each field is a JSON object:
+    Returns an array of JSON objects (\b{not an object itself!}).
     \table
         \header
             \li JSON field
@@ -203,12 +207,14 @@
             \li JSON array of application tags
         \row
             \li version
-            \li Application version. Returned as string. If application information lacks version, “0.0.0” is returned
+            \li Application version. Returned as a string. If the application information lacks
+            a version number, “0.0.0” is returned
         \row
             \li architecture
-            \li Application architecture. Returned as detected in library components of the application
+            \li Application architecture. Returned as detected in the library components of the application
 
-            If application is not native, contains “All”. Otherwise it is formed like this: mips-little_endian-32-elf
+            If the application is not native, contains \e{All}.
+            Otherwise it is formed like this: mips-little_endian-32-elf
 
             Where it is a combination of:
             \list 1
@@ -223,7 +229,7 @@
             \li Short textual app description (should be limited to 1 line, around 80-130 characters)
         \row
             \li category_id
-            \li Numeric category id matching application category field.
+            \li Numeric category id matching the application category field.
     \endtable
     \section2 app/icon
      Returns an icon for the given application id.
@@ -235,7 +241,7 @@
              \li id
              \li Application id
      \endtable
-     Returns a PNG image or a 404 error, if application does not exist
+     Returns a PNG image or a 404 error, if the application does not exist.
      \section2 app/description
      Returns a description for the given application id.
      \table
@@ -246,11 +252,11 @@
              \li id
              \li Application id
      \endtable
-     Returns application description text - either HTML or plain text.
+     Returns an application description text - either HTML or plain text.
      \section2 app/purchase
-     Returns an url which can be used for downloading the requested application for certain period of time (configurable in the settings).
-     \note This is legacy from AppStore, changing the name of this API would involve changes in reference UI.
-     The real action is preparing package for download. For discussion, contact nzamotaev@luxoft.com.
+     Returns a URL which can be used for downloading the requested application for certain period of time (configurable in the settings).
+     \note This is legacy from AppStore. Changing the name of this API would involve changes in reference UI.
+     The real action is preparing the package for download. For discussion, contact nzamotaev@luxoft.com.
      \table
          \header
              \li Parameter
@@ -274,24 +280,25 @@
              \li Successful
          \row
              \li failed
-             \li Something went wrong. Check error field for more information.
+             \li Something went wrong. Check the error field for more information.
          \row
              \li error
              \li text
-             \li If status equals to ‘failed’, contains error description.
+             \li If status equals to \e{failed}, contains an error description.
          \row
              \li url
              \li URL
-             \li URL for downloading application. Expires in time specified in ‘expiresIn’ field.
+             \li URL for downloading the application.
+             Expires in the time specified in the \c{expiresIn} field.
          \row
              \li expiresIn
              \li Integer value
-             \li Time in seconds for which download url stays valid.
+             \li Time in seconds for which the download URL stays valid.
      \endtable
 
      \section2 category/list
-     Lists all the available categories. Also returns ‘All’ metacategory, that is used to hold all available applications.
-     Returns a JSON array (not an object!). Each field is a JSON object:
+     Lists all the available categories. Also returns \e{All} metacategory, that is used to hold all available applications.
+     Returns an array of JSON objects (\b{not an object itself!}).
      \table
          \header
              \li JSON field
@@ -313,12 +320,13 @@
          \li id
          \li Id of the category.
      \endtable
-     Returns a PNG image or empty 1x1 PNG file.
-     \note Currently takes icon of the first application in the category if it exists. This should be fixed.
+     Returns a PNG image or an empty 1x1 PNG file.
+     \note Currently takes the icon of the first application in the category if it exists.
+     This should be fixed.
      \section2 upload
      Accepts remote package upload requests.
-     User must be in the “staff” group to use this API. Also requires either basic authentication,
-     or previous call to \b{login} method. This is a POST request to server, due to parameters used.
+     The user must be in the \e{staff} group to use this API. Also requires either basic authentication
+     or a previous call to the \c{login} method. This is a POST request to the server due to the parameters used.
      \table
          \header
              \li Parameter
@@ -363,24 +371,24 @@
              \li Vendor parameter missing
          \row
              \li Package validation failed
-             \li Package did not pass format/sanity validation
+             \li Package did not pass format or sanity validation
          \row
              \li Non-existing category
-             \li No category matches passed parameter
+             \li No category matches the passed parameter
          \row
              \li Non-existing vendor
              \li No vendor matches passed parameter
          \row
              \li no package to upload
-             \li There was no ‘package’ parameter in request, or it was not a POST request
+             \li There was no \c{package} parameter in the request, or it was not a POST request
      \endtable
 
     \section2 API use examples
     The deployment server exposes a HTTP API to the world. Arguments to the functions need to be provided using the
     HTTP GET/POST syntax. Returned data will be in JSON, PNG or text format, depending on the function.
-    \section3 Basic workflow
+    \section3 Workflow
     \list 1
-    \li Send a \b{hello} request to the server to get the current status and check
+    \li Send a \b{hello} request to the server to get the current status and to check
         whether your platform is compatible with this server instance:
 
         \tt http://<server>/hello?platform=AM&version=1
@@ -389,7 +397,7 @@
 
         \tt { { "status": "ok" } }
 
-    \li Login as user \b{user} with password \b{pass}:
+    \li Login as user \e{user} with password \e{pass}:
 
         \tt http://<server>/login?username=user&password=pass
 
@@ -413,7 +421,7 @@
               ] }
 
 
-    \li Request a download for a App:
+    \li Request a download for an app:
 
     \tt http://<server>/app/purchase?device_id=12345&id=com.luxoft.niceapp
 
@@ -430,12 +438,13 @@
     \endlist
 
     \section1 Installation
-    \section2 Setting up the server in virtualenv
+    \section2 Setting up the Server in virtualenv
+    Before installing dependencies in the Python virtual environment, libffi-dev package must be
+    installed. After package installation, prepare the virtual environment:
     \code
         virtualenv ./venv
         ./venv/bin/pip install -r requirements.txt
     \endcode
-    (libffi-dev is also needed)a
 
     Before running the server, make sure to adapt the \b{APPSTORE_*} settings in \b{appstore/settings.py} to your environment.
 
@@ -450,14 +459,14 @@
     \code
       ./manage.py runserver 0.0.0.0:8080
     \endcode
-    will start the server on port 8080, reachable for anyone. One can tweak the listening address to whatever fits the needs.
+    will start the server on port 8080, reachable by anyone. One can tweak the listening address to whatever fits the needs.
     \section2 Maintenance tasks
     \list
     \li Cleaning up the downloads directory:
     \code
       ./manage.py expire-downloads
     \endcode
-    will remove all files from the downloads/ directory, that are older than
+    will remove all files from the downloads directory, that are older than
     \b{settings.APPSTORE_DOWNLOAD_EXPIRY} minutes. This should be called from a cron-job (see above).
     \li Manually verifying a package for upload:
     \code