From 94cbb4d383351bb65cbc9c9617af5109112534b7 Mon Sep 17 00:00:00 2001
From: Benjamin Bertrand <benjamin.bertrand@esss.se>
Date: Fri, 20 Sep 2019 10:50:18 +0200
Subject: [PATCH] Update README and documentation

---
 README.md            | 46 ++++++++++++++++++++++++++++++++++++++------
 library/conda_env.py |  8 ++++----
 2 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 0e2f486..4a8997f 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,10 @@
 
 Ansible role to install conda on CentOS and Debian.
 
-This role includes as well a conda module that can be used to manage conda packages.
+This role includes as well:
 
-## Requirements
-
-- ansible >= 2.7
-- molecule >= 2.20
+- a `conda` module that can be used to manage conda packages.
+- a `conda_env` module that can be used to manage conda environments.
 
 ## Role Variables
 
@@ -37,7 +35,13 @@ conda_env_files:
   - https://gitlab.esss.lu.se/ics-infrastructure/conda-environments/raw/master/molecule_env.yml
 ```
 
-## Conda module
+Note that this is deprecated as it has some drawbacks:
+- the update is only based on the file content (via a handler) and not the environment itself
+- handler can't be used when using `include_role`
+
+Using the `conda_env` module is the recommended way.
+
+## conda module
 
 The `conda` module allows to install, update or remove conda packages.
 
@@ -76,6 +80,36 @@ The `conda` module allows to install, update or remove conda packages.
     environment: myapp
 ```
 
+## conda_env module
+
+The `conda_env` module allows to create, update or remove conda environments.
+
+```yaml
+- name: create myenv environment
+  conda_env:
+    name: myenv
+    state: present
+    file: /tmp/environment.yml
+
+- name: update all packages in myenv environment
+  conda_env:
+    name: myenv
+    state: latest
+
+- name: update myenv environment based on environment.yml
+  conda_env:
+    name: myenv
+    state: present
+    prune: true
+    file: /tmp/environment.yml
+
+- name: remove myenv environment
+  conda_env:
+    name: myenv
+    state: absent
+```
+
+Note that the environment.yml file shall be present locally on the host.
 
 ## Example Playbook
 
diff --git a/library/conda_env.py b/library/conda_env.py
index 736c626..ce595de 100644
--- a/library/conda_env.py
+++ b/library/conda_env.py
@@ -66,25 +66,25 @@ author:
 
 EXAMPLES = """
 - name: create myenv environment
-  conda:
+  conda_env:
     name: myenv
     state: present
     file: /tmp/environment.yml
 
 - name: update all packages in myenv environment
-  conda:
+  conda_env:
     name: myenv
     state: latest
 
 - name: update myenv environment based on environment.yml
-  conda:
+  conda_env:
     name: myenv
     state: present
     prune: true
     file: /tmp/environment.yml
 
 - name: remove myenv environment
-  conda:
+  conda_env:
     name: myenv
     state: absent
 """
-- 
GitLab