Merge pull request #48 from bioconda/recipe-docs/install

docs: improved and modernized installation instructions

Author: johanneskoester

source/index.rst

@@ -3,7 +3,7 @@
    To build the documentation locally, first create an environment using
    bioconda_utils/bioconda_utils-requirements.txt.
 
-   mamba create -p ./env --file https://raw.githubusercontent.com/bioconda/bioconda-utils/master/bioconda_utils/bioconda_utils-requirements.txt -y
+   conda create -p ./env --file https://raw.githubusercontent.com/bioconda/bioconda-utils/master/bioconda_utils/bioconda_utils-requirements.txt -y
 
    With that env activated, run:
 
@@ -22,6 +22,8 @@ biomedical research using the `conda <https://conda.io>`_ package manager.
 
 **NOTE**: *Bioconda supports only Linux (64-bit and AArch64) and macOS (x86_64 and ARM64)*
 
+.. _bioconda_setup:
+
 Usage
 =====
 

source/templates/readme.rst_t

@@ -60,9 +60,8 @@
       {% endif %}
 
    {% for dependency in package.depends %}
-   :depends {{dependency[0]}}: {% if dependency[1] %}``{{ dependency[1].replace(" ", "\xa0") }}``{% endif %}
+   :depends on {{dependency[0]}}: {% if dependency[1] %}``{{ dependency[1].replace(" ", "\xa0") }}``{% endif %}
    {%- endfor %}
-   :requirements:
 
    :additional platforms:
       {% if extra and extra['additional-platforms']|length > 0 %}
@@ -78,39 +77,63 @@
          </span>
       {% endif %}
 
-   .. rubric:: Installation
+Installation
+------------
 
-  You need a conda-compatible package manager
-  (currently either `micromamba <https://mamba.readthedocs.io>`_, `mamba <https://mamba.readthedocs.io>`_, or `conda <https://docs.conda.io/projects/conda>`_)
-  and the Bioconda channel already activated (see :ref:`set-up-channels`).
+You need a conda-compatible package manager
+(currently either `pixi <https://pixi.sh>`__, `conda <https://docs.conda.io/projects/conda>`__, or `micromamba <https://mamba.readthedocs.io>`__)
+and the Bioconda channel already activated (see :ref:`bioconda_setup`).
+Below, we show how to install with either pixi or conda (for micromamba and mamba, commands are essentially the same as with conda).
 
-  While any of above package managers is fine, it is currently recommended to use either
-  micromamba or mamba (see `here <https://mamba.readthedocs.io>`_ for installation instructions).
-  We will show all commands using mamba below, but the arguments are the same for the two
-  others.
+Pixi
+""""
 
-  Given that you already have a conda environment in which you want to have this package, install with::
+With pixi_ installed and the Bioconda channel set up (see :ref:`bioconda_setup`),
+to install globally, run::
 
-      mamba install {{ package.name }}
+    pixi global install {{ package.name }}
 
-   and update with::
+to add into an existing workspace instead, run::
 
-      mamba update {{  package.name }}
+    pixi add {{ package.name }}
 
-  To create a new environment, run::
+In the latter case, make sure to first add bioconda and conda-forge to the channels considered by the workspace::
 
-      mamba create --name myenvname {{ package.name }}
+    pixi workspace channel add conda-forge
+    pixi workspace channel add bioconda
 
-  with ``myenvname`` being a reasonable name for the environment
-  (see e.g. the `mamba docs <https://mamba.readthedocs.io>`_ for details and further options).
+Conda
+"""""
 
-  Alternatively, use the docker container::
+With conda_ installed and the Bioconda channel set up (see :ref:`bioconda_setup`), to install into an existing and activated environment, run::
 
-      docker pull quay.io/biocontainers/{{ package.name }}:<tag>
+    conda install {{ package.name }}
 
-   (see `{{package.name}}/tags`_ for valid values for ``<tag>``)
+Alternatively, to install into a new environment, run::
 
+    conda create -n envname {{ package.name }}
 
+with ``envname`` being the name of the desired environment.
+
+Container
+"""""""""
+
+Alternatively, every Bioconda package is available as a container image for usage with your preferred container runtime.
+For e.g. docker, run::
+
+    docker pull quay.io/biocontainers/{{ package.name }}:<tag>
+
+(see `{{package.name}}/tags`_ for valid values for ``<tag>``).
+
+Integrated deployment
+"""""""""""""""""""""
+
+Finally, note that many scientific workflow management systems directly integrate both conda and container based software deployment.
+Thus, workflow steps can be often directly annotated to use the package, leading to automatic deployment by the respective workflow management system, thereby improving reproducibility and transparency.
+Check the documentation of your workflow management system to find out about the integration.
+
+.. _conda: https://conda.io
+.. _pixi: https://pixi.sh
 .. |downloads_{{package.name}}| image:: https://img.shields.io/conda/dn/bioconda/{{package.name}}.svg?style=flat
    :target: https://anaconda.org/bioconda/{{package.name}}
    :alt:   (downloads)