fix doc

docs/apidoc/api.rst

+Global API
+==========
+
+.. automodule:: enoslib.api
+   :members:
+   :undoc-members:

docs/apidoc/enoslib.infra.enos_chameleonbaremetal.rst

-enoslib\.infra\.enos\_chameleonbaremetal package
-================================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_chameleonbaremetal\.provider module
----------------------------------------------------------
-
-.. automodule:: enoslib.infra.enos_chameleonbaremetal.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_chameleonbaremetal
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.enos_chameleonkvm.rst

-enoslib\.infra\.enos\_chameleonkvm package
-==========================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_chameleonkvm\.provider module
----------------------------------------------------
-
-.. automodule:: enoslib.infra.enos_chameleonkvm.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_chameleonkvm
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.enos_g5k.rst

-enoslib\.infra\.enos\_g5k package
-=================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_g5k\.api module
--------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.api
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.enos\_g5k\.error module
----------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.error
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.enos\_g5k\.provider module
-------------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.enos\_g5k\.remote module
-----------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.remote
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.enos\_g5k\.schema module
-----------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.schema
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.enos\_g5k\.utils module
----------------------------------------
-
-.. automodule:: enoslib.infra.enos_g5k.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_g5k
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.enos_openstack.rst

-enoslib\.infra\.enos\_openstack package
-=======================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_openstack\.provider module
-------------------------------------------------
-
-.. automodule:: enoslib.infra.enos_openstack.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_openstack
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.enos_static.rst

-enoslib\.infra\.enos\_static package
-====================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_static\.provider module
----------------------------------------------
-
-.. automodule:: enoslib.infra.enos_static.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_static
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.enos_vagrant.rst

-enoslib\.infra\.enos\_vagrant package
-=====================================
-
-Submodules
-----------
-
-enoslib\.infra\.enos\_vagrant\.provider module
-----------------------------------------------
-
-.. automodule:: enoslib.infra.enos_vagrant.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra.enos_vagrant
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/enoslib.infra.rst

-enoslib\.infra package
-======================
-
-Subpackages
------------
-
-.. toctree::
-
-    enoslib.infra.enos_chameleonbaremetal
-    enoslib.infra.enos_chameleonkvm
-    enoslib.infra.enos_g5k
-    enoslib.infra.enos_openstack
-    enoslib.infra.enos_static
-    enoslib.infra.enos_vagrant
-
-Submodules
-----------
-
-enoslib\.infra\.provider module
--------------------------------
-
-.. automodule:: enoslib.infra.provider
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.infra\.utils module
-----------------------------
-
-.. automodule:: enoslib.infra.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: enoslib.infra
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/apidoc/index.rst

+.. enoslib documentation master file, created by
+   sphinx-quickstart on Thu Sep 21 21:45:39 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+API documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api.rst
+   infra.rst
+

docs/apidoc/enoslib.rst → docs/apidoc/infra.rst

-enoslib package
-===============
+Provider APIs
+=============
 
-Subpackages
------------
-
-.. toctree::
-
-    enoslib.infra
-
-Submodules
-----------
-
-enoslib\.api module
+Base Provider Class
 -------------------
 
-.. automodule:: enoslib.api
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-enoslib\.constants module
--------------------------
-
-.. automodule:: enoslib.constants
+.. automodule:: enoslib.infra.provider
     :members:
     :undoc-members:
     :show-inheritance:
 
-enoslib\.errors module
+Vagrant Provider Class
 ----------------------
 
-.. automodule:: enoslib.errors
+.. automodule:: enoslib.infra.enos_vagrant.provider
     :members:
     :undoc-members:
     :show-inheritance:
 
-enoslib\.host module
---------------------
+    .. autodata:: FLAVORS
 
-.. automodule:: enoslib.host
+Grid5000 Provider Class
+-----------------------
+
+.. automodule:: enoslib.infra.enos_g5k.provider
     :members:
     :undoc-members:
     :show-inheritance:
 
-enoslib\.task module
---------------------
+    .. autodata::
+
+Openstack Provider Class
+------------------------
 
-.. automodule:: enoslib.task
+.. automodule:: enoslib.infra.enos_openstack.provider
     :members:
     :undoc-members:
     :show-inheritance:
 
-enoslib\.utils module
----------------------
+Chameleon(kvm) Provider Class
+-----------------------------
 
-.. automodule:: enoslib.utils
+.. automodule:: enoslib.infra.enos_chameleonkvm.provider
     :members:
     :undoc-members:
     :show-inheritance:
 
+Chameleon(bare metal) Provider Class
+------------------------------------
 
-Module contents
----------------
-
-.. automodule:: enoslib
+.. automodule:: enoslib.infra.enos_chameleonbaremetal.provider
     :members:
     :undoc-members:
     :show-inheritance:

docs/apidoc/modules.rst

-enoslib
-=======
-
-.. toctree::
-   :maxdepth: 4
-
-   enoslib

docs/conf.py

@@ -172,3 +172,7 @@ texinfo_documents = [
 rst_epilog = """
 .. |enoslib| replace:: EnOSlib
 """
+
+# Document also the __init__
+autoclass_content = "both"
+

docs/getting-started/_tmp_enos_/enos-0.out

-192.168.142.245 : 0.04 0.03 0.03 0.03 0.03
-192.168.142.244 : 41.91 41.80 41.46 42.16 41.14
-
-       2 targets
-       2 alive
-       0 unreachable
-       0 unknown addresses
-
-       0 timeouts (waiting for response)
-      10 ICMP Echos sent
-      10 ICMP Echo Replies received
-       0 other ICMP received
-
- 0.03 ms (min round trip time)
- 20.8 ms (avg round trip time)
- 42.1 ms (max round trip time)
-        4.071 sec (elapsed real time)
-

docs/index.rst

@@ -20,13 +20,5 @@ using tasks.
    :maxdepth: 2
    :caption: Contents:
 
-   getting-started
-   apidoc/modules
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-
-.. * :ref:`modindex`
-.. * :ref:`search`
+   tutorials/index.rst
+   apidoc/index.rst

docs/tutorials/grid5000.rst

+.. _installation:
+
+Working with Grid'5000
+======================
+
+Let's adapt the vagrant tutorial to Grid'5000.
+
+Installation
+------------
+
+On Grid'5000, you can got with a virtualenv :
+
+.. code-block:: bash
+
+    $ virtualenv venv
+    $ source venv/bin/activate
+    $ pip install -U pip
+
+    $ pip install enoslib
+
+Using the API
+-------------
+
+The following ``tuto_grid5000.py`` implements the desired workflow.
+
+.. literalinclude:: grid5000/tuto_grid5000.py
+   :language: python
+   :linenos:
+
+- You can launch the script using :
+
+    .. code-block:: bash
+
+        $ python tuto_grid5000.py
+
+
+- The content of the generated inventory should looks like the following:
+
+    .. literalinclude:: grid5000/hosts
+     :language: python

docs/tutorials/grid5000/hosts

+[control]
+paravance-9-kavlan-4.rennes.grid5000.fr ansible_host=paravance-9-kavlan-4.rennes.grid5000.fr ansible_ssh_user=root ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' enos_devices="['eth0']" my_network=eth0
+parasilo-7-kavlan-4.rennes.grid5000.fr ansible_host=parasilo-7-kavlan-4.rennes.grid5000.fr ansible_ssh_user=root ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' enos_devices="['eth0']" my_network=eth0
+[compute]
+parasilo-7-kavlan-4.rennes.grid5000.fr ansible_host=parasilo-7-kavlan-4.rennes.grid5000.fr ansible_ssh_user=root ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' enos_devices="['eth0']" my_network=eth0%

docs/tutorials/grid5000/tuto_grid5000.py

+from enoslib.api import generate_inventory, emulate_network, validate_network
+from enoslib.infra.enos_g5k.provider import G5k
+
+import logging
+import os
+
+logging.basicConfig(level=logging.INFO)
+
+provider_conf = {
+    "resources": {
+        "machines": [{
+            "role": "control",
+            "cluster": "paravance",
+            "nodes": 1,
+            "primary_network": "n1",
+            "secondary_networks": []
+        },{
+
+            "roles": ["control", "compute"],
+            "cluster": "parasilo",
+            "nodes": 1,
+            "primary_network": "n1",
+            "secondary_networks": []
+        }],
+        "networks": [{
+            "id": "n1",
+            "type": "kavlan",
+            "role": "my_network",
+            "site": "rennes",
+         }]
+    }
+}
+
+# path to the inventory
+inventory = os.path.join(os.getcwd(), "hosts")
+
+# claim the resources
+provider = G5k(provider_conf)
+roles, networks = provider.init()
+
+# generate an inventory compatible with ansible
+generate_inventory(roles, networks, inventory, check_networks=True)

docs/tutorials/index.rst

+.. enoslib documentation master file, created by
+   sphinx-quickstart on Thu Sep 21 21:45:39 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Tutorials
+=========
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    vagrant
+    grid5000
+    using-tasks

docs/tutorials/using-tasks.rst

+.. _installation:
+
+Using the Tasks API
+===================
+
+Let's consider the following use case :
+
+- Get machines from vagrant
+- Apply some network constraints
+- Validate those network constraints
+
+Installation
+------------
+
+.. code-block:: bash
+
+    $ pip install enoslib
+
+.. note::
+
+  It's a good practice to use a virtualenv or python version manager like `pyenv`_.
+Using the API
+-------------
+
+The following ``enos.py`` implements the desired workflow.
+
+.. literalinclude:: using-tasks/step1.py
+   :language: python
+   :linenos:
+
+- Lines 5-18 describe the wanted resources. Here we want two machines with roles
+  ``control`` and ``compute`` respectively. These two nodes will have one network card
+  configured using the same network whose role is ``n1``.
+
+  .. note::
+
+    Machine roles and network roles are transparent to the |enoslib|. The semantic is
+    left to the application using it.
+
+- Lines 19-23 describe some network constraints. Those constraints will be set
+  between the nodes of the two groups ``control`` and ``compute`` on the network
+  ``n1``.
+
+- Lines 27-34 enforce the wanted workflow.
+
+  .. note::
+
+    Under the hoods, |enoslib| leverages Ansible for many routine tasks and
+    thus an inventory must be generated. This is exactly the purpose of
+    :py:func:`enoslib.api.generate_inventory` function.  When
+    ``check_networks`` is set, |enoslib| will auto-discover the mapping between
+    the network roles and the available network interfaces. This is convenient
+    when it comes to deal with non uniform (or non deterministic) network cards
+    naming.
+
+
+- You can launch the script using :
+
+  .. code-block:: bash
+
+      $ python enos.py
+
+
+- The content of the generated inventory should looks like the following:
+
+  .. literalinclude:: using-tasks/hosts
+     :language: python
+
+- You can check the generated reports by :py:func:`enoslib.api.validate_network` in ``_tmp_enos_``.
+
+
+  .. literalinclude:: using-tasks/_tmp_enos_/enos-0.out
+     :language: python
+     :emphasize-lines: 2
+
+Using tasks
+-----------
+
+
+.. literalinclude:: using-tasks/step2.py
+   :language: python
+   :emphasize-lines: 33,45,51
+   :lines: 33-65
+
+- Using Tasks is a neat way to organize your program into a workflow.
+
+- The environment (``env`` variable in the above) is a way to (1) store
+  information on the current execution and (2) pass information from one task
+  to another. It is automatically restored at the beginning of a task and saved
+  at the end.
+
+
+- You can launch the script using :
+
+  .. code-block:: bash
+
+    $ python enos.py
+
+
+Integrating with a command line parser
+--------------------------------------
+
+Let's integrate our tasks with a command line parser. Here we choose `click`_.
+First enusre that it is installed:
+
+.. code-block:: bash
+
+    $ pip install click
+
+- Change the content of ``enos.py`` to the following:
+
+  .. literalinclude:: using-tasks/step3.py
+     :language: python
+     :lines: 32-75
+
+- For the sake of illustration, we added a flag (``--force``) to the command
+  line which allows to force the recreation of the virtual machines (see
+  :py:meth:`enoslib.infra.provider.Provider.init`).  Since every provider
+  supports this flag we pass its value to the ``ìnit`` method.
+
+- You will now have access to the command line interface :
+
+  .. code-block:: bash
+
+      $ python enos.py --help
+      Usage: enos.py [OPTIONS] COMMAND [ARGS]...
+
+      Options:
+        --help  Show this message and exit.
+
+      Commands:
+        emulate   Emulates the network.
+        up        Starts a new experiment using vagrant
+        validate  Validates the network constraints.
+
+.. references::
+
+.. _click: http://click.pocoo.org/
+.. _pyenv: https://github.com/pyenv/pyenv