python commands

index.rst

@@ -11,23 +11,30 @@ Targeted at individual studies and study consortia, `OBiBa <http://obiba.org/>`_
 Agate is the `OBiBa <http://obiba.org/>`_'s central authentication server which intends to be easy to install and to use. Agate centralizes also some user related services such as profile management, and a notification system using emails.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents
 
    introduction
    installation
    configuration
 
 .. toctree::
-   :maxdepth: 2
-   :caption: User Guides
+   :maxdepth: 1
+   :caption: Web User Guides
 
    web-user-guide/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Python User Guides
+
    python-user-guide/index
+   python-user-guide/add-user
+   python-user-guide/delete-user
 
 .. toctree::
-   :maxdepth: 2
-   :caption: API
+   :maxdepth: 1
+   :caption: OAuth2 API
 
    oauth2-api/index
    oauth2-api/authorization-code-grant-flow

introduction.rst

@@ -1,11 +1,6 @@
 Introduction
 ============
 
-Targeted at individual studies and study consortia, OBiBa software stack (Opal, Mica2 etc.) provides a software solution for epidemiological data management, analysis and publication. While Opal, the core data warehouse application, provides all the necessary tools to import, transform and describe data, Mica provides everything needed to build personalized web data portals and publish content of research activities of both studies and consortia. Based on the content defined in Mica, Drupal is the preferred platform to build your personalized web portal.
-
-Agate is the OBiBa's central authentication server which intends to be easy to install and to use. Agate centralizes also some user related services such as profile management, and a notification system using emails.
-
-
 Users, Groups and Applications
 ------------------------------
 

oauth2-api/index.rst

@@ -1,5 +1,5 @@
-OAuth2 API
-==========
+Introduction
+============
 
 Summary
 -------

python-user-guide/add-user.rst

@@ -0,0 +1,57 @@
+Add User
+========
+
+Add a new user.
+
+.. code-block:: bash
+
+  agate add-user <CREDENTIALS> [OPTIONS] [EXTRA]
+
+Credentials
+-----------
+
+Authentication is done by username/password credentials.
+
+==================================== ====================================
+Option                               Description
+==================================== ====================================
+``--agate AGATE, -ag AGATE``         Agate server base url.
+``--user USER, -u USER``             User name. User with appropriate permissions is expected depending of the REST resource requested.
+``--password PASSWORD, -p PASSWORD`` User password.
+==================================== ====================================
+
+Options
+-------
+
+==================================================== ====================================================
+Option                                               Description
+==================================================== ====================================================
+``--name NAME``                                      The user name, required and unique.
+``--email EMAIL``                                    The user email, required and unique.
+``--upassword UPASSWORD``                            The user password, required.
+``--first-name FIRST_NAME``                          The user first name.
+``--last-name LAST_NAME``                            The user last name.
+``--applications [APPLICATIONS [APPLICATIONS ...]]`` The applications in which the user can sign-in, space separated.
+``--groups [GROUPS [GROUPS ...]]``                   The groups to which the user belongs, space separated.
+``--role ROLE``                                      The role of the user. Default is "agate-user", which gives only the right to user to access to its own profile. Other possible value is "agate-administrator".
+``--status STATUS``                                  Only active users can sign-in. Default value is "ACTIVE". Other possible values are: "PENDING", "APPROVED" or "INACTIVE".
+==================================================== ====================================================
+
+Extras
+------
+
+================= =================
+Option            Description
+================= =================
+``-h, --help``    Show the command help's message
+``--verbose, -v`` Verbose output
+================= =================
+
+Example
+-------
+
+Add a new user.
+
+.. code-block:: bash
+
+  agate add-user -ag http://localhost:8081 -u administrator -p password --name user1 --email user1@example.org --applications mica drupal

python-user-guide/delete-user.rst

@@ -0,0 +1,50 @@
+Delete User
+===========
+
+Delete a user.
+
+.. code-block:: bash
+
+  agate delete-user <CREDENTIALS> [OPTIONS] [EXTRA]
+
+Credentials
+-----------
+
+Authentication is done by username/password credentials.
+
+==================================== ====================================
+Option                               Description
+==================================== ====================================
+``--agate AGATE, -ag AGATE``         Agate server base url.
+``--user USER, -u USER``             User name. User with appropriate permissions is expected depending of the REST resource requested.
+``--password PASSWORD, -p PASSWORD`` User password.
+==================================== ====================================
+
+Options
+-------
+
+=================== ===================
+Option              Description
+=================== ===================
+``--name NAME``     The user name, mutually exclusive with email.
+``--email EMAIL``   The user email, mutually exclusive with name.
+=================== ===================
+
+Extras
+------
+
+================= =================
+Option            Description
+================= =================
+``-h, --help``    Show the command help's message
+``--verbose, -v`` Verbose output
+================= =================
+
+Example
+-------
+
+Delete a user by its name.
+
+.. code-block:: bash
+
+  agate delete-user -ag http://localhost:8081 -u administrator -p password --name user1

python-user-guide/index.rst

@@ -1,2 +1,120 @@
-Python Client User Guide
-========================
+Introduction
+============
+
+Agate Python client, a command line scripting tool written in Python, enables automation of tasks in a Agate server.
+
+Requirements
+------------
+
+Python 2.x must be installed on the system. See more about `Python <https://www.python.org/>`_.
+
+Installation
+------------
+
+You can install Agate Python Client via the following two methods:
+
+* use the Debian/RPM package manager
+* use a Python package
+
+Debian Package Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the `OBiBa Debian Repository <http://www.obiba.org/pages/pkg/>`_ instructions and run:
+
+.. code-block:: bash
+
+  sudo apt-get install agate-python-client
+
+RPM Package Installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the `OBiBa RPM Repository <http://www.obiba.org/pages/rpm/>`_ instructions and run:
+
+.. code-block:: bash
+
+  sudo yum install agate-python-client
+
+Python Package Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This type of package is cross-platform (Linux, Windows, Mac).
+
+**Install on Linux or Mac**
+
+1. `Download the most recent version <https://download.obiba.org/agate/stable/>`_
+2. Decompress the file and enter the installation folder:
+
+.. code-block:: bash
+
+  tar xvzf agate-python-client-X.XX.tar.gz
+  cd agate-python-client-X.XX
+
+3. Install the package:
+
+.. code-block:: bash
+
+  sudo python setup.py install --record installed_files.lst
+
+.. note::
+  The *--record* will generate a list of installed files on your system. Since there is no uninstaller, you can use this file to remove the Agate Python Client package. You can do this by executing the following command:
+  ``sudo cat installed_files.lst | xargs rm -rf``
+
+**Install on Windows**
+
+* Using Cygwin
+
+You can install Cygwin, making sure that CURL, Python, gcc are included and follow these steps inside a Cygwin BASH window:
+
+.. code-block:: bash
+
+  cd /usr/lib
+  cp libcurl.dll.a libcurl.a
+  cd <your-desired-dir>
+  curl -C - -O http://download.obiba.org/agate/stable/agate-python-client-X.XX.tar.gz
+  tar xzvf agate-python-client-X.XX.tar.gz
+  cd agate-python-client-X.XX
+  python setup.py install --record installed_files.lst
+
+* Using plain Windows tools
+
+This Windows installation is the most complicated one but does not required any third party tools. You are required to do a few manual installations before the package is fully usable. The following steps were tested on a Windows 7.
+
+1. You must have Python installed on your Windows system. Run this `installer <http://www.python.org/ftp/python/2.7.5/python-2.7.5.msi>`_ in case you don't have one.
+2. Download the `Google protobuf binary <http://code.google.com/p/protobuf/downloads/detail?name=protoc-2.5.0-win32.zip&can=2&q=>`_ and make sure that its containing folder is in your path.
+3. Download the `Google protobuf source <http://code.google.com/p/protobuf/downloads/detail?name=protobuf-2.5.0.zip>`_ package containing the setup.py file and follow these steps:
+
+.. code-block:: bash
+
+  unzip protobuf-2.5.0.zip
+  cd protobuf-2.5.0/python
+  python setup.py install
+
+4. Go to the `Python Libs <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ site and download the file pycurl-7.19.0.win-amd64-py2.7.‌exe
+5. Run the installer and follow the instructions until the package is installed
+6. `Download the most recent version <https://download.obiba.org/agate/stable/>`_ and follow these steps:
+
+.. code-block:: bash
+
+  unzip http://download.obiba.org/agate/stable/agate-python-client-X.XX.zip
+  cd agate-python-client-X.XX
+  python setup.py bdist_wininst
+  cd dist
+
+7. Execute the generated installer and follow the instructions (agate-python-client-X.XX.win-amd64.exe)
+
+Usage
+-----
+
+To get the options of the command line:
+
+.. code-block:: bash
+
+  agate --help
+
+This command will display which sub-commands are available. Further, given a subcommand obtained from command above, its help message can be displayed via:
+
+.. code-block:: bash
+
+  agate <subcommand> --help
+
+This command will display available subcommands.

web-user-guide/index.rst

@@ -1,2 +1,2 @@
-Web Application User Guide
-==========================
+Introduction
+============