Travis lint and API documentation (#2)

approved
(Baptiste Grenier) #1

Travis lint and API documentation (#2)

  • Import API documentation
  • Typo and spell
  • Linkt markdown and rst using travis.
  • Fix linting errors
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 0000000..3d7d165
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,15 @@
+---
+language: python
+python:
+  - "2.7"
+  - "3.6"
+install:
+  - gem install mdl
+  - pip install rstcheck
+  - pip install sphinx
+script:
+  # Linting
+  # https://github.com/markdownlint/markdownlint
+  - mdl -s relaxed README.md
+  # https://github.com/myint/rstcheck
+  - rstcheck --report warning source/*.rst
diff --git a/source/api.rst b/source/api.rst
new file mode 100644
index 0000000..d691faa
--- /dev/null
+++ b/source/api.rst
@@ -0,0 +1,72 @@
+.. toctree::
+
+API
+---
+
+Most if not all operations can be performed using the Onedata API.
+
+The official documentation is: https://onedata.org/#/home/api.
+
+.. important:: In order to be able to access the `Onedata APIs`, ian access
+   token is required. See below for instructions on how to generate one.
+   to generate an access token.
+
+Getting an API access token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tokens have to be generated from the **EGI DataHub** (Onezone) interface as
+documented in :ref:`auth-token-using-web-interface` or using a command line
+call as documented hereafter.
+
+The following variables should be set:
+
+* ``OIDC_TOKEN``: OpenID Connect Access token, see
+  https://wiki.egi.eu/wiki/Federated_Cloud_OpenStack_Providers#Obtaining_an_access_token
+  for obtaining it.
+* ``ONEZONE_HOST``: name or IP of the Onezone host (to use Onezone API).
+* ``ONEPROVIDER_HOST``: name or IP of the Oneprovider host (to use Oneprovider API).
+
+.. code-block:: console
+
+   ONEZONE_HOST=datahub.egi.eu
+   OIDC_TOKEN=<OIDC_ACCESS_TOKEN>
+   curl -H "X-Auth-Token: egi:$OIDC_TOKEN" -X POST \
+     -H 'Content-type: application/json' -d '{}' \
+     https://$ONEZONE_HOST/api/v3/onezone/user/client_tokens
+
+Registering a Handle for a file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prerequisites: access to a Handle service registered in the Onezone.
+See
+https://onedata.org/#/home/documentation/doc/using_onedata/handle_services.html
+for documentation on registering a new Handle service or ask a Onezone
+administrator to authorize you to use an existing Handle service already
+registered in the Onezone.
+
+
+The following variables should be set:
+
+* ``API_ACCESS_TOKEN``: `Onedata API access token <https://onedata.org/docs/doc/using_onedata/using_onedata_from_cli.html#authentication>`_
+* ``ONEZONE_HOST``: name or IP of the Onezone host (to use Onezone API).
+
+.. code-block:: console
+
+   # Getting the IDs of the available Handle Services
+   curl -sS --tlsv1.2 -H "X-Auth-Token: $API_ACCESS_TOKEN" \
+     -X GET \
+     "https://datahub.egi.eu/api/v3/onezone/user/handle_services"
+   HANDLE_SERVICE=<HANDLE_SERVICE_ID>
+   # Getting details about a specific Handle service
+   curl -sS --tlsv1.2 -H "X-Auth-Token: $API_ACCESS_TOKEN" \
+     -X GET \
+     "https://$ONEZONE_HOST/api/v3/onezone/user/handle_services/$HANDLE_SERVICE"
+   # Getting the ID of a space or directory of a space
+   # TO BE DONE
+   RESOURCE=<RESOURCE_ID>
+   # Registering a handle
+   curl -sS --tlsv1.2 -H "X-Auth-Token: $API_ACCESS_TOKEN" \
+     -H "Content-type: application/json" \
+     -X POST \
+     -d '{"handleServiceId": "$HANDLE_SERVICE", "resourceType": "Share", "resourceId": "$RESOURCE", "metadata": "..." }' \
+     https://$ONEZONE_HOST/api/v3/handles
diff --git a/source/clients.rst b/source/clients.rst
index e78b1c9..1afe917 100644
--- a/source/clients.rst
+++ b/source/clients.rst
@@ -3,11 +3,11 @@
 Clients
 -------
 
-The `Oneclient` code and basic documnentation is available on GitHub:
-https://github.com/onedata/oneclient
+The Oneclient code and basic documentation is available on
+`GitHub <https://github.com/onedata/oneclient>`_.
 
-The officiel documentation is:
-https://onedata.org/#/home/documentation/doc/using_onedata/oneclient.html
+The official documentation is hosted on the
+`Onedata homepage <https://onedata.org/#/home/documentation/doc/using_onedata/oneclient.html>`_.
 
 Using the web interface
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -43,6 +43,7 @@ Using the web interface
    The data space can be managed (ie. uploading/downloading/managing files and
    metadata, manging space access) using the web browser.
 
+.. _auth-token-using-web-interface:
 
 Generating tokens for using Oneclient or APIs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -50,7 +51,7 @@ Generating tokens for using Oneclient or APIs
 .. important:: In order to be able to access your spaces using `Oneclient` or
    `APIs`, it's required to generate an access token.
 
-Tokens have to be generated from the `DataHub` (Onezone) interface.
+Tokens have to be generated from the **EGI DataHub** (Onezone) interface.
 
 .. figure:: _static/datahub-space-token.png
    :alt: EGI DataHub token management
@@ -68,8 +69,8 @@ releases).
 
 The following variables have to be exported in the container:
 
-* `ONECLIENT_ACCESS_TOKEN`: access token allowing to access **all** the spaces.
-* `ONECLIENT_PROVIDER_HOST`: name or IP of the Oneprovider the client should connect to.
+* ``ONECLIENT_ACCESS_TOKEN``: access token allowing to access **all** the spaces.
+* ``ONECLIENT_PROVIDER_HOST``: name or IP of the Oneprovider the client should connect to.
 
 .. important:: In order to be able to use FUSE, the container should run in `privileged` mode.
 
@@ -87,8 +88,8 @@ The following variables have to be exported in the container:
    root@81dbd7e84438 /]# oneclient /tmp/space
    root@81dbd7e84438 /]# ls /tmp/space
 
-Here the data is mounted in `/tmp/space`, creating a file into it will push it
-to the oneprovider and it will be accessible up in the web interface and from
+Here the data is mounted in ``/tmp/space``, creating a file into it will push it
+to the Oneprovider and it will be accessible up in the web interface and from
 other providers supporting the space.
 
 For a real production usage it's preferable to use the Oneclient container as a
@@ -97,19 +98,20 @@ source for a volume mounted into another container.
 Testing Oneclient in a Oneclient docker container with NFS or samba
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Docker containers for the oneclient are available, the existing versions can be
-seen in docker hub: https://hub.docker.com/r/onedata/oneclient/tags
+Docker containers for the Oneclient are available, the existing versions can be
+seen on the `Oneclient docker hub <https://hub.docker.com/r/onedata/oneclient/tags>`_.
 
-It's possible to use the most recent version by specifying the `latest` tag,
-and it's also quite common to use a version identical to the other components
-versions that can be seen on the Onezone and Oneprovider pages.
+It's possible to use the most recent version by specifying the ``latest`` tag.
+We also recommend using same version as shown on the Onezone and
+Oneprovider pages.
 
 The following variables have to be exported to be used in the container:
 
-* `ONECLIENT_ACCESS_TOKEN`: access token allowing to access **all** the spaces.
-* `ONECLIENT_PROVIDER_HOST`: name or IP of the Oneprovider the client should connect to.
+* ``ONECLIENT_ACCESS_TOKEN``: access token allowing to access **all** the spaces.
+* ``ONECLIENT_PROVIDER_HOST``: name or IP of the Oneprovider the client should connect to.
 
-.. important:: In order to be able to use FUSE, the container should run in `privileged` mode.
+.. important:: In order to be able to use FUSE, the container should run in
+   ``privileged`` mode.
 
 .. code-block:: console
 
@@ -121,7 +123,7 @@ The following variables have to be exported to be used in the container:
    Oneclient has been successfully mounted in '/mnt/oneclient'
 
 Now the client will run in the background and the data will now be available
-through `samba/CIFS` or `nfs` protocols:
+through **samba/CIFS** or **nfs** protocols:
 
 .. code-block:: console
 
@@ -131,20 +133,22 @@ through `samba/CIFS` or `nfs` protocols:
 
 So the data can be accessed at
 
-* `smb://172.17.0.2/onedata`

[... diff too long, it was truncated ...]

GitHub sha: c591da18

(Bruce Becker) Approved #2