Updated and cleaned up docs (spietras#35)

README.md

@@ -34,27 +34,65 @@ http_archive(
 
 load("@rules_conda//:defs.bzl", "conda_create", "load_conda", "register_toolchain")
 
+load_conda(quiet = False)
+
+conda_create(
+    name = "py3_env",
+    environment = "@//:environment.yml",
+    quiet = False,
+)
+
+register_toolchain(py3_env = "py3_env")
+```
+
+After that, all Python targets will use the environment specified in `register_toolchain`.
+
+See below for more advanced example.
+
+## Advanced example
+
+This example shows all possibilities of `rules_conda`:
+
+```starlark
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "rules_conda",
+    sha256 = "c5ad3a077bddff381790d64dd9cc1516b8133c1d695eb3eff4fed04a39dc4522",
+    url = "https://github.com/spietras/rules_conda/releases/download/0.0.6/rules_conda-0.0.6.zip",
+)
+
+load("@rules_conda//:defs.bzl", "conda_create", "load_conda", "register_toolchain")
+
 load_conda(
-    installer = "miniconda",  # "miniconda" or "miniforge", defaults to "miniconda"
-    quiet = False,  # use True to hide conda output
-    version = "4.10.3",  # optional, defaults to 4.10.3
+    conda_version = "4.10.3",  # version of conda to download, default is 4.10.3
+    installer = "miniforge",  # which conda installer to download, either miniconda or miniforge, default is miniconda
+    install_mamba = True,  # whether to install mamba, which is a faster drop-in replacement for conda, default is False
+    mamba_version = "0.17.0",  # version of mamba to install, default is 0.17.0
+    quiet = False,  # True if conda output should be hidden, default is True
+    timeout = 600,  # how many seconds each execute action can take, default is 3600
+)
+
+conda_create(
+    name = "py3_env",  # name of the environment, default is my_env
+    environment = "@//:py3_environment.yml",  # label pointing to environment configuration file
+    use_mamba = True,  # Whether to use mamba to create the conda environment. If this is True, install_mamba must also be True	False
+    clean = False,  # True if conda cache should be cleaned (less space taken, but slower subsequent builds), default is False
+    quiet = False,  # True if conda output should be hidden	True, default is True
+    timeout = 600,  # how many seconds each execute action can take, default is 3600
 )
 
 conda_create(
-    name = "my_env",
-    timeout = 600,  # each execute action can take up to 600 seconds
-    clean = False,  # use True if you want to clean conda cache (less space taken, but slower subsequent builds)
-    environment = "@//:environment.yml",  # label pointing to environment.yml file
-    quiet = False,  # use True to hide conda output
+    name = "py2_env",  # name of the environment, default is my_env
+    environment = "@//:py2_environment.yml",  # label pointing to environment configuration file
 )
 
 register_toolchain(
-    py3_env = "my_env",
+    py2_env = "py2_env",  # python2 is optional
+    py3_env = "py3_env",
 )
 ```
 
-After that, all Python targets will use the environments specified in `register_toolchain`.
-
 ## Who should use this?
 
 These rules allow you to download and install `conda`, create `conda` environments and register Python toolchain from environments.

docs/docs/usage/api.md

@@ -13,7 +13,7 @@
     | `conda_version` | Version of `conda` to download                                                             | `4.10.3`               |
     | `installer`     | Which `conda` installer to download, either `miniconda` or `miniforge`                     | `miniconda`            |
     | `install_mamba` | Whether to install `mamba`, which is a faster drop-in replacement for `conda`              | `False`                |
-    | `mamba_version` | Version of `conda` to install                                                              | `0.17.0`               |
+    | `mamba_version` | Version of `mamba` to install                                                              | `0.17.0`               |
     | `quiet`         | `True` if `conda` output should be hidden                                                  | `True`                 |
     | `timeout`       | How many seconds each execute action can take                                              | `3600`                 |
 

docs/docs/usage/example.md

@@ -29,25 +29,15 @@ http_archive(
 
 load("@rules_conda//:defs.bzl", "conda_create", "load_conda", "register_toolchain")
 
-load_conda(
-    installer = "miniconda",  # "miniconda" or "miniforge", defaults to "miniconda"
-    quiet = False,  # use True to hide conda output
-    version = "4.10.3",  # optional, defaults to 4.10.3
-    install_mamba = False, # use True to use mamba, which a faster drop-in replacement for conda
-)
+load_conda(quiet = False)
 
 conda_create(
-    name = "my_env",
-    timeout = 600,  # each execute action can take up to 600 seconds
-    clean = False,  # use True if you want to clean conda cache (less space taken, but slower subsequent builds)
-    environment = "@//:environment.yml",  # label pointing to environment.yml file
-    quiet = False,  # use True to hide conda output
-    use_mamba = False, # use True to use mamba, which a faster drop-in replacement for conda
+    name = "py3_env",
+    environment = "@//:environment.yml",
+    quiet = False,
 )
 
-register_toolchain(
-    py3_env = "my_env",
-)
+register_toolchain(py3_env = "py3_env")
 ```
 
 This will download `conda`, create your environment and register it so that all Python targets can use it by default.
@@ -62,6 +52,6 @@ This will run `main.py` inside the created environment.
 
 If environment configuration doesn't change then subsequent runs will simply reuse the environment.
 Otherwise the environment will be recreated from scratch, so that it always reflects the configuration.
-However, if you set the `clean` flag to `False` in `conda_create` then the downloaded package data will be reused so you don't need to download everything everytime.
+However, if the `clean` flag is set to `False` (the default) in `conda_create` then the downloaded package data will be reused so you don't need to download everything everytime.
 
 Also see [here](https://github.com/spietras/rules_conda/tree/main/example) for a complete example with all the code available.

example/WORKSPACE

@@ -3,15 +3,15 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 ### RULES_PYTHON ###
 http_archive(
     name = "rules_python",
-    url = "https://github.com/bazelbuild/rules_python/releases/download/0.5.0/rules_python-0.5.0.tar.gz",
     sha256 = "cd6730ed53a002c56ce4e2f396ba3b3be262fd7cb68339f0377a45e8227fe332",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/0.5.0/rules_python-0.5.0.tar.gz",
 )
 
 ### RULES_CONDA ###
 # use this instead of http_archive if you cloned the repo and want to use the local version
 local_repository(
-   name = "rules_conda",
-   path = "../",
+    name = "rules_conda",
+    path = "../",
 )
 
 # use this instead of local_repository if you want to use the release version
@@ -25,31 +25,20 @@ local_repository(
 load("@rules_conda//:defs.bzl", "conda_create", "load_conda", "register_toolchain")
 
 # download and install conda
-load_conda(
-    conda_version = "4.10.3",  # optional, defaults to 4.10.3
-    install_mamba = False,  # use True to install mamba, which a faster drop-in replacement for conda
-    mamba_version = "0.17.0",  # optional, defaults to 0.17.0
-    quiet = False,  # use True to hide conda output
-)
+load_conda(quiet = False)
 
 # create environment with python2
 conda_create(
-    name = "py2_env",
-    timeout = 600,  # each execute action can take up to 600 seconds
-    clean = False,  # use True if you want to clean conda cache (less space taken, but slower subsequent builds)
+    name = "py2_env",  # name of the environment
     environment = "@//third_party/conda:py2_environment.yml",  # label pointing to environment.yml file
-    quiet = False,  # use True to hide conda output
-    use_mamba = False,  # use True to use mamba, which a faster drop-in replacement for conda
+    quiet = False,  # use True to hide conda output, default is True
 )
 
 # create environment with python3
 conda_create(
-    name = "py3_env",
-    timeout = 600,  # each execute action can take up to 600 seconds
-    clean = False,  # use True if you want to clean conda cache (less space taken, but slower subsequent builds)
+    name = "py3_env",  # name of the environment
     environment = "@//third_party/conda:py3_environment.yml",  # label pointing to environment.yml file
-    quiet = False,  # use True to hide conda output
-    use_mamba = False,  # use True to use mamba, which a faster drop-in replacement for conda
+    quiet = False,  # use True to hide conda output, default is True
 )
 
 # register pythons from environment as toolchain