Merge branch 'change-install-instructions' into 'main'

Simplifies installation and development instructions so that...

See merge request !10

doc/develop.rst

@@ -33,6 +33,14 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
    ``../profile``.
 
 
+.. tip::
+
+   Please refer :ref:`idiap-devtools.install.running` for details on how to
+   setup the ``mamba-run-on`` shell function to simplify the various
+   commands below. If you decide to skip this, remember to properly activate
+   and deactivate the environments everytime.
+
+
 .. tab:: pip
 
    In this variant, the latest (beta) versions of internally developed
@@ -45,10 +53,10 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
 
       $ git clone <PACKAGE-URL>  # e.g. git clone git@gitlab.idiap.ch/software/clapp
       $ cd <PACKAGE>  # e.g. cd clapp
-      $ conda activate base  # only required if conda/mamba is not on your $PATH
-      (base) $ mamba create -n dev python=3.10 pip
-      (base) $ conda activate dev
-      (dev) $ pip install --pre --index-url https://token:<YOUR-GITLAB-TOKEN>@gitlab.idiap.ch/api/v4/groups/software/-/packages/pypi/simple --extra-index-url https://pypi.org/simple --constraint ../profile/python/pip-constraints.txt --editable '.[qa,doc,test]'
+      $ mamba-run-on base mamba create -n dev python=3.10 pip
+      $ mamba-run-on dev pip install --pre --index-url https://token:<YOUR-GITLAB-TOKEN>@gitlab.idiap.ch/api/v4/groups/software/-/packages/pypi/simple --extra-index-url https://pypi.org/simple --constraint ../profile/python/pip-constraints.txt --editable '.[qa,doc,test]'
+      $ conda activate dev
+      (dev) $ # `dev` environment is now ready, just develop
 
    .. note::
 
@@ -67,7 +75,7 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
       apply the same instructions above to locally install dependencies and the
       package itself.
 
-      The base Python version in this case will be that used to create the virtual
+      The Python version in this case will match that used to create the virtual
       environment.
 
 
@@ -85,11 +93,11 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
 
       $ git clone <PACKAGE>
       $ cd <PACKAGE>
-      $ conda activate base  # only required if conda/mamba is not on your $PATH
-      (base) $ devtool env -vv .
-      (base) $ mamba env create -n dev -f environment.yaml
-      (base) $ conda activate dev
-      (dev) $ pip install --no-build-isolation --no-dependencies --editable .
+      $ mamba-run-on idiap-devtools devtool env -vv .
+      $ mamba-run-on base mamba env create -n dev -f environment.yaml
+      $ mamba-run-on dev pip install --no-build-isolation --no-dependencies --editable .
+      $ conda activate dev
+      (dev) $ # `dev` environment is now ready, just develop
 
    .. note::
 
@@ -112,6 +120,7 @@ test suite, or the quality assurance (pre-commit) checks:
 
 .. code:: sh
 
+   $ conda activate dev
    (dev) $ pre-commit run --all-files  # quality assurance
    (dev) $ pytest -sv tests/ # test units
    (dev) $ sphinx-build doc sphinx  # documentation
@@ -145,13 +154,13 @@ similar to the above, except you will git-clone and pip-install more packages:
       $ git clone <PACKAGE-A>
       $ cd <PACKAGE-A>
       $ git clone <PACKAGE-B> src/<PACKAGE-B>
-      $ conda activate base  # only required if conda/mamba is not on your $PATH
-      (base) $ mamba create -n dev python=3.10 pip
+      $ mamba-run-on base mamba create -n dev python=3.10 pip
       # get the constraints for the "target" development environment.
       # this is just an example:
-      (base) $ curl -O constraints.txt https://gitlab.idiap.ch/software/dev-profile/-/raw/main/python/pip-constraints.txt
-      (base) $ conda activate dev
+      $ curl -O constraints.txt https://gitlab.idiap.ch/software/dev-profile/-/raw/main/python/pip-constraints.txt
+      $ conda activate dev
       (dev) $ for pkg in "src/package-b" "."; do pip install --pre --index-url https://token:<YOUR-GITLAB-TOKEN>@gitlab.idiap.ch/api/v4/groups/software/-/packages/pypi/simple --extra-index-url https://pypi.org/simple --constraint constraints.txt --editable "${pkg}[qa,doc,test]"; done
+      (dev) $ # `dev` environment is now ready, just develop
 
 
 .. tab:: conda
@@ -168,11 +177,11 @@ similar to the above, except you will git-clone and pip-install more packages:
       $ git clone <PACKAGE-A>
       $ cd <PACKAGE-A>
       $ git clone <PACKAGE-B> src/<PACKAGE-B>
-      $ conda activate base  # only required if conda/mamba is not on your $PATH
-      (base) $ devtool env -vv src/package-b .
-      (base) $ mamba env create -n dev -f environment.yaml
-      (base) $ conda activate dev
+      $ mamba-run-on idiap-devtools devtool env -vv src/package-b .
+      $ mamba-run-on base mamba env create -n dev -f environment.yaml
+      $ conda activate dev
       (dev) $ for pkg in "src/package-b" "."; do pip install --no-build-isolation --no-dependencies --editable "${pkg}"
+      (dev) $ # `dev` environment is now ready, just develop
 
 
 Installing all constrained packages
@@ -186,10 +195,9 @@ packages, we only provide this option:
 
 .. code:: sh
 
-   $ conda activate base  # only required if conda/mamba is not on your $PATH
-   (base) $ devtool fullenv -vv
-   (base) $ mamba env create -n dev -f environment.yaml
-   (base) $ conda activate dev
+   $ mamba-run-on idiap-devtools devtool fullenv -vv
+   $ mamba-run-on base mamba env create -n dev -f environment.yaml
+   $ conda activate dev
    (dev) $ for pkg in "src/*"; do pip install --no-build-isolation --no-dependencies --editable "${pkg}"
 
 

doc/install.rst

@@ -8,34 +8,115 @@
  Installation
 ==============
 
-First install mamba_ or conda (preferably via mambaforge_).  Then, in its
-``base`` environment, install this package using one of the methods below:
+First install mamba_ or conda (preferably via mambaforge_, as it is already
+setup to use conda-forge_ as its main distribution channel).  Then, create a
+new environment, containing this package:
 
 
 .. tab:: mamba/conda (RECOMMENDED)
 
    .. code-block:: sh
 
-      mamba install -n base -c https://www.idiap.ch/software/biosignal/conda/label/beta -c conda-forge idiap-devtools
+      # installs the latest release on conda-forge:
+      mamba create -n idiap-devtools idiap-devtools
+
+      # OR, installs the latest development code:
+      mamba create -n idiap-devtools -c https://www.idiap.ch/software/biosignal/conda/label/beta idiap-devtools
 
 
 .. tab:: pip
 
    .. warning::
 
-      While this is possible for testing purposes, it is **not recommended**.
-      Pip-installing this package may break your ``base`` conda environment.
-      Moreover, you will need to ensure both ``mamba`` and ``boa`` packages are
-      installed on the ``base`` environment.
+      While this is possible for testing purposes, it is **not recommended**,
+      as this package depends on conda/mamba for some of its functionality.  If
+      you decide to do so, create a new conda/mamba environment, and
+      pip-install this package on it.
 
    .. code-block:: sh
 
-      conda activate base
-      # next step only required if using miniconda or miniforge (skip it if using mambaforge_)
-      conda install -c conda-forge mamba boa
+      # creates the new environment
+      mamba create -n idiap-devtools python=3 pip conda mamba conda-build boa
+      conda activate idiap-devtools
+
+      # installs the latest release on PyPI:
+      pip install idiap-devtools
+
+      # OR, installs the latest development code:
       pip install git+https://gitlab.idiap.ch/software/idiap-devtools
 
 
+.. _idiap-devtools.install.running:
+
+Running
+-------
+
+This package contains a single command-line executable named ``devtool``, which
+in turn contains subcommands with various actions.  To run the main
+command-line tool, you must first activate the environment where it is
+installed in, and then call it on the command-line:
+
+.. code-block:: sh
+
+   conda activate idiap-devtools
+   devtool --help
+   conda deactivate  # to go back to the previous state
+
+
+It is possible to use the command ``conda run`` to, instead, automatically
+prefix the execution of ``devtool`` with an environment activation, and follow
+it with a deactivation.  This allows to compact the above form into a
+"one-liner":
+
+.. code-block:: sh
+
+   mamba --no-banner run -n idiap-devtools --no-capture-output --live-stream devtool --help
+
+
+.. tip::
+
+   If you use a POSIX shell, such as bash or zsh, you can add a function to your
+   environment, so that the above command-line becomes easier to access:
+
+   .. code-block:: sh
+
+      # Runs a command on a prefixed environment, if the environment is not the
+      # the current one.  Otherwise, just runs the command itself.
+      # argument 1: the conda environment name where the program exists
+      # other arguments: program and arguments to be executed at the prefixed
+      # conda environment
+      function mamba-run-on {
+          # if the environment is set, then just run the command
+          if [[ "${CONDA_DEFAULT_ENV}" == "${1}" ]]; then
+              "${@:2}"
+          else
+              mamba --no-banner run -n ${1} --no-capture-output --live-stream "${@:2}"
+          fi
+      }
+
+    You can use it like this:
+
+    .. code-block:: sh
+
+       mamba-run-on idiap-devtools devtool --help
+       alias devtool="mamba-run-on idiap-devtools devtool"
+
+
+.. warning::
+
+   The ``devtool`` application requires that ``mamba``/``conda`` are available
+   on the environment it executes.  When using ``mamba``/``conda`` to create
+   new environments, ensure you are using the ones from the ``base``
+   environment.  Creating new environments as sub-environments of the
+   ``idiap-devtools`` environment may have surprising effects.  To this end, we
+   advise you create a second alias that ensures ``mamba`` is always executed
+   from the ``base`` environment:
+
+    .. code-block:: sh
+
+       alias mamba="mamba-run-on base mamba"
+
+
 .. _idiap-devtools.install.setup:
 
 Setup