[doc] Simplified usage even further

doc/develop.rst

@@ -32,15 +32,6 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
    instructions, we assume your development profile is located at
    ``../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
@@ -53,9 +44,9 @@ 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
-      $ 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]'
+      $ mamba create -n dev python=3.10 pip
       $ 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]'
       (dev) $ # `dev` environment is now ready, just develop
 
    .. note::
@@ -93,10 +84,10 @@ development environment through pip_ (with `the --editable option <pip-e_>`_).
 
       $ git clone <PACKAGE>
       $ cd <PACKAGE>
-      $ 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 .
+      $ mamba run -n idiap-devtools --live-stream devtool env -vv .
+      $ mamba env create -n dev -f environment.yaml
       $ conda activate dev
+      (dev) $ pip install --no-build-isolation --no-dependencies --editable .
       (dev) $ # `dev` environment is now ready, just develop
 
    .. note::
@@ -154,7 +145,7 @@ 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>
-      $ mamba-run-on base mamba create -n dev python=3.10 pip
+      $ mamba create -n dev python=3.10 pip
       # get the constraints for the "target" development environment.
       # this is just an example:
       $ curl -O constraints.txt https://gitlab.idiap.ch/software/dev-profile/-/raw/main/python/pip-constraints.txt
@@ -177,8 +168,8 @@ 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>
-      $ mamba-run-on idiap-devtools devtool env -vv src/package-b .
-      $ mamba-run-on base mamba env create -n dev -f environment.yaml
+      $ mamba run -n idiap-devtools --live-stream devtool env -vv src/package-b .
+      $ 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
@@ -195,8 +186,8 @@ packages, we only provide this option:
 
 .. code:: sh
 
-   $ mamba-run-on idiap-devtools devtool fullenv -vv
-   $ mamba-run-on base mamba env create -n dev -f environment.yaml
+   $ mamba run -n idiap-devtools --live-stream devtool fullenv -vv
+   $ 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

@@ -63,58 +63,25 @@ installed in, and then call it on the command-line:
    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":
+It is possible to use the command ``mamba run`` (or ``conda run``, if you
+installed miniforge) 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"
+   mamba run -n idiap-devtools --live-stream devtool --help
 
 
 .. 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"
+   new environments, ensure you are using the mamba executable **from the
+   ``base`` environment**.  Creating new environments as sub-environments of
+   the ``idiap-devtools`` environment may have surprising effects.  A way to do
+   this is to first activate the ``base`` environment, and then create the new
+   environment.
 
 
 .. _idiap-devtools.install.setup: