Update docs

DEVELOPERS.md

@@ -3,20 +3,20 @@
 This document aims to collect the guidelines for the development of MiCADO. This should be treated as an evolving document.
 
 # Coding Style #
- 
+
  - Python: PEP-8 [[4]]
  - YAML: 4 Space indent
 
 # Versioning #
 We adapted _semantic versioning 2.0.0_ [[3]]. This infers the following renaming of previous releases:
 
  - V3 -> 0.3.0 (further modifications will result in 0.3.1, 0.3.2, etc.)
- - V4 -> 0.4.0 
+ - V4 -> 0.4.0
 
 Previous releases (V1 and V2) should remain untouched.
 
 # Repositories #
-We should use separate GIT repositories for each separate logical unit within the _micado-scale_ github.com organization as follows: 
+We should use separate GIT repositories for each separate logical unit within the _micado-scale_ github.com organization as follows:
 
 1. Each component should be placed in its own repository with the prefix _component-_, e.g., _component-alert\_manager_.
 2. The _micado_ repository is the main repository, containing "glue" files (e.g., cloud-init and/or docker-compose related ones).
@@ -28,11 +28,11 @@ The master branch of each repository should contain an ISSUE\_TEMPLATE.md for is
 
 # Branching #
 We adapt the _successful GIT branching method_ [[1]] with the following modifications:
- 
+
  1. The _master_ branch should always represent the latest stable release.
  2. _develop_ branch is for development.
  3. In each repository, from its _develop_ branch, for each major release, a release branch should be created.
- 4. Release branches should be named based on their major and minor versions: v_MAJOR_._MINOR_.x  
+ 4. Release branches should be named based on their major and minor versions: v_MAJOR_._MINOR_.x
     - E.g., for the 0.4 releases, the branch should be called _0.4.x_ (x is literal, represents that all 0.4 releases, e.g., 0.4.0, 0.4.1, etc. are based on this branch).
 
 # Releases #
@@ -48,7 +48,7 @@ For the 0.3.x release branch:
 
 
 # Commit Guidelines #
-We adopt the _angular.js commit guidelines_ [[2]] with some modifications. We do not pre-define scopes. The scope part should describe the affected part in the commit message. 
+We adopt the _angular.js commit guidelines_ [[2]] with some modifications. We do not pre-define scopes. The scope part should describe the affected part in the commit message.
 
 # Dev Docker registry #
 We use a private docker registry to develop MiCADO components. This registry is running on CloudSigma and protected with basic authentication.

user_documentation/prepare.sh

@@ -18,7 +18,7 @@ source "$PDIR"/bin/activate
 pip install --upgrade pip
 
 # Install the locally checked out packages:
-pip install -r requirements.txt 
+pip install -r requirements.txt
 
 set +ex
 

user_documentation/requirements.txt

@@ -4,4 +4,4 @@ ruamel.yaml==0.16.10
 pycryptodome==3.9.8
 python-novaclient==17.2.0
 openstacksdk==0.48.0
-ansible==2.9.12
+ansible==2.10.0

user_documentation/rst/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'MiCADO'
-copyright = '2018, Cloud Orchestration at the Level of Application'
+copyright = '2020, Cloud Orchestration at the Level of Application'
 author = 'Attila Farkas'
 
 # The short X.Y version

user_documentation/rst/micado.rst

@@ -31,7 +31,7 @@ install those before using MiCADO client library. For reference, they are:
 * pycryptodome==3.9.8
 * python-novaclient==17.2.0
 * openstacksdk==0.48.0
-* ansible==2.9.12
+* ansible==2.10.0
 
 Get the MiCADO Client Library
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -45,11 +45,13 @@ Simply clone the respository and add the location to your PYTHONPATH
   $ MC_PATH="/usr/local/lib/micado-client"
   $ git clone https://github.com/micado-scale/micado-client $MC_PATH
   $ export PYTHONPATH="$PYTHONPATH:$MC_PATH"
+  $ mkdir -p ~/.micado-cli
+  $ touch ~/.micado-cli/credentials-cloud-api.yml
 
 Specify cloud credentials
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-Specify cloud credential for MiCADO master VM creation. This file should
-be saved at ``~/.micado-cli/credentials-cloud-api.yml``
+Specify cloud credential for MiCADO master VM creation. Please,
+edit ``~/.micado-cli/credentials-cloud-api.yml``
 
 .. code:: yaml
 
@@ -69,47 +71,80 @@ be saved at ``~/.micado-cli/credentials-cloud-api.yml``
 Example
 -------
 
-For more detail, see the Documentation Reference section below
-
-**Usage with a launcher:**
-
 .. note::
     Before you start testing, make sure the authentication data in the correct place.
 
-.. code:: Python
+For more details, see the Documentation Reference section below.
+There are three use-cases identified for using micado-client.
 
-    from micado import MicadoClient
+**Use-case 1**
 
-    client = MicadoClient(launcher="openstack")
-    ID = client.master.create(auth_url='yourendpoint',
-                         project_id='project_id',
-                         image='image_name or image_id',
-                         flavor='flavor_name or flavor_id',
-                         network='network_name or network_id',
-                         keypair='keypair_name or keypair_id',
-                         security_group='security_group_name or security_group_id')
- 
-    client.applications.list()
-    client.applications.create(app_id="hello-world",
-                               url="https://example.com/repo/hw_adt.yaml")
-    client.applications.get("hello-world")
-    client.applications.delete("hello-world")
-
-    client.master.destroy(ID)
-
-
-
-**Usage without a launcher:**
+MiCADO master is created with the help of MiCADO client library. The create and destroy methods
+are invoked in the same program i.e. storing and retrieving the ``client.master`` object is not needed.
 
 .. code:: Python
 
     from micado import MicadoClient
 
-    client = MicadoClient(endpoint="https://micado/toscasubmitter/",
-                          version="v2.0",
-                          verify=False,
-                          auth=("ssl_user", "ssl_pass"))
+    client = MicadoClient(launcher="openstack")
+    client.master.create(
+        auth_url='yourendpoint',
+        project_id='project_id',
+        image='image_name or image_id',
+        flavor='flavor_name or flavor_id',
+        network='network_name or network_id',
+        keypair='keypair_name or keypair_id',
+        security_group='security_group_name or security_group_id'
+        )
     client.applications.list()
+    client.master.destroy()
+
+**Use-case 2**
+
+MiCADO master is created with the help of MiCADO client library. The create and destroy methods
+are invoked in seperate programs i.e. storing and retrieving the ``client.master`` object is needed.
+
+    .. code:: Python
+
+        from micado import MicadoClient
+
+        client = MicadoClient(launcher="openstack")
+        master_id = client.master.create(
+            auth_url='yourendpoint',
+            project_id='project_id',
+            image='image_name or image_id',
+            flavor='flavor_name or flavor_id',
+            network='network_name or network_id',
+            keypair='keypair_name or keypair_id',
+            security_group='security_group_name or security_group_id'
+            )
+        client.applications.list()
+        << store your master_id >>
+        << exiting... >>
+        -------------------------------------------------------------
+        << start >>
+        ...
+        master_id = << retrieve master_id >>
+        client = MicadoClient(launcher="openstack")
+        client.master.attach(master_id = master_id)
+        client.applications.list()
+        client.master.destroy()
+
+**Use-case 3**
+
+MiCADO master is created independently from the MiCADO client library. The create and destroy methods
+are not invoked since the client library used only for handling the applications.
+
+    .. code:: Python
+
+        from micado import MicadoClient
+        client = MicadoClient(
+            endpoint="https://micado/toscasubmitter/",
+            version="v2.0",
+            verify=False,
+            auth=("ssl_user", "ssl_pass")
+            )
+        client.applications.list()
 
 Documentation Reference
 -----------------------
@@ -123,5 +158,4 @@ Documentation Reference
 
 Roadmap
 -------
-* Handle multiple MiCADO-master VM
-* Support additional Cloud interface
+* Support additional Cloud interface (e.g EC2)

user_documentation/rst/release_notes.rst

@@ -5,7 +5,7 @@ Release Notes
 | See more detailed notes about upgrading in :ref:`whatsnew`
 
 v0.9.1 (1 October 2020)
-=====================
+=======================
 
 - Add support for Oracle Cloud Infrastructure
 - Add support for Ubuntu 20.04 LTS