Sdg23 update user guide installation instructions

doc/source/installation.rst

@@ -1,140 +1,227 @@
 .. -*- coding: utf-8 -*-
 
 ====================
-Installation
+Installation Guide
 ====================
 
-The latest versions of **MDAnalysis** can be installed using `conda` or `pip`.
-Currently, the conda releases only support serial calculations.
-If you plan to use the parallel OpenMP algorithms, you need to
-install MDAnalysis with pip and have a working OpenMP installation.
+The latest version of **MDAnalysis** can be installed using :ref:`mamba-installation` (recommended),
+or :ref:`pip-installation`. If you need to install MDAnalysis from source, follow :ref:`source-installation`
+for stable releases. If you are a contributor or developer working on MDAnalysis, follow the
+:ref:`development-installation` for editable installation and code modifications.
 
-MDAnalysis has a separate :ref:`test suite <mdanalysistests>` **MDAnalysisTests** that is required to run the test cases and examples.
-The test files change less frequently, take up around 90 MB of space,
-and are not needed for daily use of MDAnalysis. However, they are often used in examples,
-including many in this User Guide. If you are not interested in developing
-MDAnalysis or using the example files, you most likely don't need the tests. If you want to
-run examples in the User Guide, install the tests.
-The tests are distributed separately from the main package.
+Currently, the :ref:`mamba-installation` installs a version of MDAnalysis that does **not** include `OpenMP`_
+acceleration due to limitations in precompiled conda packages. If you need `OpenMP`_-enabled features,
+consider installing via :ref:`pip-installation` and compiling from source with a compatible compiler and
+OpenMP support.
+
+**MDAnalysisTests** is optional and is a separate :ref:`test suite <mdanalysistests>` used
+for verifying MDAnalysis installations and running User Guide examples. It is not required for
+daily use, but some tutorials rely on it. The package is approximately 90 MB and is not updated frequently.
+If you plan to use tutorial examples or contribute to MDAnalysis, installing it is recommended.
+
+MDAnalysis supports specific Python versions. For the latest supported versions, please refer to the
+`CHANGELOG`_ or the `PyPI`_. Ensure you have a compatible Python version installed before proceeding.
 
 .. note::
+    MDAnalysis supports **Linux**, **macOS**, and **Windows**.
 
-    If you are installing on Windows, you must have
-    Microsoft Visual C++ 14.0 installed. If your installation
-    fails with the error message:
+    - If you encounter errors on **Windows** related to **Microsoft Visual C++ 14.0**, install the required **Build Tools for Visual Studio** from: `Microsoft Visual Studio Downloads`_.
+    - If you encounter any other issues following these instructions, seek help on `GitHub Discussions (Installation)`_.
 
-        error: Microsoft Visual C++ 14.0 is required. Get it with "Build Tools for Visual Studio": https://visualstudio.microsoft.com/downloads/
+.. _mamba-installation:
 
-    Try installing Build Tools for Visual Studio from
-    https://visualstudio.microsoft.com/downloads/ (scroll
-    down to the Tools for Visual Studio section).
+mamba/conda
+===========
 
+For most users, `mamba`_ is the **recommended** way to install MDAnalysis. It is a faster drop-in
+replacement for `conda`_ and efficiently handles dependencies. We also recommend creating a new
+environment for MDAnalysis to ensure a clean and isolated installation.
 
-If you encounter any issues following these instructions, please
-ask for help on `GitHub Discussions (Installation)`_.
+MDAnalysis supports two common ways to install with `mamba`_:
 
-.. _`GitHub Discussions (Installation)`: https://github.com/MDAnalysis/mdanalysis/discussions/categories/installation
+**1. Recommended: Use Mambaforge**
 
-conda
-=====
+`Mambaforge`_ is a minimal `conda`_ distribution that includes `mamba`_ by default, uses the `conda-forge`_ channel
+(preferred for MDAnalysis) and avoids clutter from `Anaconda`_ base packages.
 
-If you use ``conda`` to manage your Python environment, we highly recommend creating a new environment for MDAnalysis.
-This will ensure that you have a clean installation of MDAnalysis and its dependencies, and will not interfere with other packages you may have installed.
-We further recommend that you install and use ``mamba``, a faster drop-in replacement for ``conda``.
+To install MDAnalysis with `Mambaforge`_, follow the `mambaforge installation instructions`_ and then
+run the following commands to install MDAnalysis:
 
 .. code-block:: bash
 
-    conda create --name mdanalysis
-    conda activate mdanalysis
-    conda install -c conda-forge mamba
+    mamba create -n mdanalysis -c conda-forge mdanalysis
+    mamba activate mdanalysis
 
-To install the latest stable version of MDAnalysis via ``conda``, use the following command. This installs all dependencies needed for full analysis functionality (excluding external programs such as `HOLE`_):
+To install the :ref:`test suite <mdanalysistests>` (optional, ~90 MB):
 
 .. code-block:: bash
 
-    mamba install -c conda-forge mdanalysis
+    mamba install -c conda-forge MDAnalysisTests
 
-To upgrade:
+To upgrade, use:
 
 .. code-block:: bash
 
     mamba update mdanalysis
 
-To install the tests:
+If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress bar support:
 
 .. code-block:: bash
 
-    mamba install -c conda-forge MDAnalysisTests
+    mamba install -c conda-forge ipywidgets
+
+**2. Alternative: Use conda with conda-forge**
 
-If you intend to use MDAnalysis in JupyterLab, you will have to install
-an extra package for the progress bar in analysis classes:
+If you prefer using `conda`_ directly (e.g., installed via `Anaconda installer`_), create a new environment with packages from the `conda-forge`_ channel:
 
 .. code-block:: bash
 
-    conda install -c conda-forge nodejs
-    jupyter labextension install @jupyter-widgets/jupyterlab-manager
+    conda create -n mdanalysis -c conda-forge mdanalysis
+    conda activate mdanalysis
+
+To install optional packages:
+
+.. code-block:: bash
+
+    conda install -c conda-forge MDAnalysisTests ipywidgets
+
+.. _pip-installation:
 
 pip
-=====
-The following command will install or upgrade the latest stable version of MDAnalysis via ``pip``, with core dependencies. This means that some packages required by specific analysis modules will not be installed.
+===
+
+The following command will install or upgrade the latest stable version of MDAnalysis via `pip`_ with core dependencies.
+This means that some packages required by specific analysis modules will not be installed.
 
 .. code-block:: bash
 
     pip install --upgrade MDAnalysis
 
-If you need to install a fully-featured MDAnalysis, add the ``analysis`` tag. As with ``conda``, this will not install external programs such as `HOLE`_.
+MDAnalysis offers several optional dependency groups (“extra tags”) that you can install with pip to enable additional features:
+
+- ``analysis``: optional dependencies for various analysis modules.
+- ``extra_formats``: support for additional file formats.
+- ``parallel``: install dask to enable parallel analysis across multiple cores or machines.
+- ``doc``: install documentation build dependencies (e.g. Sphinx, themes).
+
+To see the full list of available extras, check the `pyproject.toml file`_.
+
+To install with optional features, use pip with one or more extras:
 
 .. code-block:: bash
 
-    pip install --upgrade MDAnalysis[analysis]
+    pip install --upgrade MDAnalysis[analysis,extra_formats,parallel]
 
-To install/upgrade tests:
+To install or upgrade the :ref:`test suite <mdanalysistests>` (optional, ~90 MB):
 
 .. code-block:: bash
 
     pip install --upgrade MDAnalysisTests
 
-If you intend to use MDAnalysis in JupyterLab, you will have to install
-an extra package for the progress bar in analysis classes:
+If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress bar support:
 
 .. code-block:: bash
 
-    pip install nodejs
-    jupyter labextension install @jupyter-widgets/jupyterlab-manager
+    pip install ipywidgets
 
+.. _source-installation:
 
-Development versions
-====================
-To install development versions of MDAnalysis, you can compile it from source. In order to install from source, you will need ``numpy`` and ``cython``. See :ref:`create-virtual-environment` for instructions on how to create a full development environment.
+Install from source
+===================
+
+This section is for **users** who want to install a **specific stable version** of MDAnalysis
+(e.g., for reproducibility or to debug a release). This is **not** intended for development or code contributions.
+If you're a developer, see :ref:`development-installation`.
+
+To install from source, you must first ensure that your environment already contains all necessary dependencies.
+We recommend you check the :ref:`create-virtual-environment` to set up a clean development environment
+with all required dependencies. We recommend using `mamba`_ or `conda`_ to manage this setup.
+
+Follow the steps in:
+
+- `Set up with conda-forge`_
+- `Set up with mamba`_
+
+MDAnalysis uses different Git branches for different purposes:
+
+- **package-X.Y.Z**: These are tags, not branches, and represent stable release versions (e.g., package-2.9.0). These tags are ideal if you need reproducibility, debugging, or version locking. You can browse all tags on the GitHub `Branches page`_.
+- **develop**: The `develop`_ branch is the default and active development branch. If you're contributing to MDAnalysis or want the latest unreleased features, base your work on this branch (see :ref:`development-installation`).
+
+Clone the repository and check out the tag corresponding to the desired version:
 
 .. code-block:: bash
 
     git clone https://github.com/MDAnalysis/mdanalysis
     cd mdanalysis
-    # assuming you have already installed required dependencies
+    git checkout package-<version>
+
+You will now be in a detached HEAD state, which is expected when checking out a tag. This allows you to explore or install that version without affecting branches.
+If you plan to make changes, you can create a new branch based on the tag:
+
+.. code-block:: bash
+
+    git switch -c my-fix-based-on-2.9.0
+
+To install MDAnalysis from this version:
+
+.. code-block:: bash
+
+    pip install package/.
+
+To run tests:
+
+.. code-block:: bash
+
+    pip install MDAnalysisTests
+
+.. _development-installation:
+
+Install for development
+==========================
+
+This section is for **contributors and developers** who want to modify MDAnalysis
+or contribute to its development. You’ll install MDAnalysis in **editable mode**, which allows you to make code changes
+without reinstalling the package each time.
+
+Before installing, follow the steps described in the :ref:`source-installation` to set up a clean environment
+with all dependencies.
+
+Once your environment is ready, install MDAnalysis in editable mode:
+
+.. code-block:: bash
+
+    git clone https://github.com/MDAnalysis/mdanalysis
+    cd mdanalysis
+    git switch develop    # work on the develop branch
+    git checkout -b my-feature-branch  # Create a new branch for your changes
     pip install -e package/
 
-And to install the test suite:
+Installing in editable mode (`-e`) means that any changes you make to the MDAnalysis source code are immediately
+available without needing to reinstall.
+
+If you plan to run tests you can install the test suite:
 
 .. code-block:: bash
 
+    # Install the test suite (optional but recommended for contributors)
     pip install -e testsuite/
 
+For more on how to set up and contribute, refer to the :ref:`contributing` guide.
 
 Testing
 -------
 
-The tests rely on the `pytest` and `numpy` packages, which must also be installed. Run tests with:
+The tests rely on the `pytest`_ and `numpy`_ packages, which must also be installed. Run tests with:
 
 .. code-block:: bash
 
     pytest --disable-pytest-warnings --pyargs MDAnalysisTests
 
 All tests should pass (i.e. no FAIL, ERROR); SKIPPED or XFAIL are ok. If anything fails or gives an error,
-`ask on GitHub Discussions <https://github.com/MDAnalysis/mdanalysis/discussions>`_ or `raise an issue <https://github.com/MDAnalysis/mdanalysis/issues>`_.
+ask on `GitHub Discussions`_ or `raise an issue`_.
 
-Testing MDAnalysis can take a while, as there are quite a few tests.
-The plugin `pytest-xdist <https://github.com/pytest-dev/pytest-xdist>`_ can be used to run tests in parallel.
+Running MDAnalysis tests can take some time, as there are many test cases.
+The plugin `pytest-xdist`_ can be used to run tests in parallel.
 
 .. code-block:: bash
 
@@ -148,7 +235,7 @@ You can pass any additional compiler flags for the C/C++ compiler using the ``ex
 This allows you to add any additional compiler options required for your architecture.
 
 For example, ``extra_cflags`` can be used to tune your MDAnalysis installation for your current architecture using the `-march`, `-mtune`, `-mcpu` and related compiler flags.
-*Which* particular compiler flags to use depends on your CPU architecture. An example for an x86_64 machine would be to change the line in `setup.cfg` as follows:
+The optimal compiler flags depend on your CPU architecture. Commonly recommended settings are:
 
 .. code-block:: diff
 
@@ -157,22 +244,24 @@ For example, ``extra_cflags`` can be used to tune your MDAnalysis installation f
 
 Use of these flags can give a significant performance boost where the compiler can effectively autovectorise.
 
-Be sure to use the recommended flags for your target architecture. For example, ARM platforms recommend using ``-mcpu`` *instead* of ``-mcpu``, while
-PowerPC platforms prefer *both* ``-mcpu`` and ``-mtune``.
+Be sure to use the recommended flags for your target architecture. In many cases,
+``-march`` and ``-mcpu`` can be used together or separately, and their behavior depends
+on your platform and compiler version. For example, ARM platforms often prefer ``-mcpu``,
+while PowerPC may use both ``-mcpu`` and ``-mtune``. Refer to the `GCC documentation on -march`_
+and `-mcpu`_ for platform-specific guidance.
 
-Full dicussion of the these flags is available elsewhere (such as here in this wiki_ or in this ARM_ blog post) and a list of supported options should be provided by your compiler. The list for GCC_ is provided here.
+Full discussion of these flags is available elsewhere (such as here in this `wiki`_ or in this `ARM`_ blog post) and a list of supported options should be provided by your compiler. The list for GCC_ is provided here.
 
 .. warning::
-    Use of these compiler options is considered **advanced** and may reduce the binary compatibility of MDAnalysis significantly, especially if using `-march`,
-    making it usable only on a matching CPU architecture to the one it is compiled on. We **strongly** recommend that you run the test suite on your intended platform
-    before proceeding with analysis.
+    These compiler options are **advanced** and may reduce binary compatibility. In particular, using `-march` may restrict MDAnalysis to the exact CPU architecture it was compiled on.
+    We **strongly recommend** that you run the test suite on your intended platform before proceeding with analysis.
 
 In cases where you might encounter multiple CPU architectures (e.g. on a supercomputer where the login node and compute node have different architectures), you should avoid changing these options unless you are experienced with compiling software in these situations.
 
 Additional datasets
 ===================
 
-MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with ``conda`` or ``pip``:
+MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with `mamba`_ / `conda`_ or `pip`_:
 
 .. code-block:: bash
 
@@ -183,9 +272,35 @@ MDAnalysisData_ is an additional package with datasets that can be used in examp
 
 This installation does not download all the datasets; instead, the datasets are cached when they are first downloaded using a Python command.
 
-
-.. _`HOLE`: http://www.holeprogram.org
 .. _GCC: https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html
 .. _MDAnalysisData: https://www.mdanalysis.org/MDAnalysisData/
 .. _wiki: https://wiki.gentoo.org/wiki/GCC_optimization#-march
 .. _ARM: https://community.arm.com/arm-community-blogs/b/tools-software-ides-blog/posts/compiler-flags-across-architectures-march-mtune-and-mcpu
+.. _pip: https://pip.pypa.io/en/latest/index.html
+.. _mamba: https://anaconda.org/conda-forge/mamba
+.. _conda: https://docs.conda.io/projects/conda/en/latest/
+.. _source: https://github.com/MDAnalysis/mdanalysis/
+.. _GitHub Discussions (Installation): https://github.com/MDAnalysis/mdanalysis/discussions/categories/installation
+.. _Microsoft Visual Studio Downloads: https://visualstudio.microsoft.com/downloads/
+.. _pytest: https://docs.pytest.org/en/stable/
+.. _numpy: https://numpy.org/
+.. _Github discussions: https://github.com/MDAnalysis/mdanalysis/discussions
+.. _raise an issue: https://github.com/MDAnalysis/mdanalysis/issues
+.. _pytest-xdist: https://github.com/pytest-dev/pytest-xdist
+.. _OpenMP: https://www.openmp.org/
+.. _mambaforge installation instructions: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html
+.. _Mambaforge: https://github.com/conda-forge/miniforge#mambaforge
+.. _conda-forge: https://conda-forge.org/
+.. _Anaconda: https://www.anaconda.com/products/distribution
+.. _ipywidgets: https://ipywidgets.readthedocs.io/en/stable/
+.. _Releases page: https://github.com/MDAnalysis/mdanalysis/releases
+.. _Set up with conda-forge: https://userguide.mdanalysis.org/stable/contributing_code.html#with-conda-forge-packages
+.. _Set up with mamba: https://userguide.mdanalysis.org/stable/contributing_code.html#with-mamba-conda
+.. _develop: https://github.com/MDAnalysis/mdanalysis/tree/develop
+.. _Branches page: https://github.com/MDAnalysis/mdanalysis/branches/all
+.. _CHANGELOG: https://github.com/MDAnalysis/mdanalysis/blob/develop/package/CHANGELOG
+.. _PyPI: https://pypi.org/project/MDAnalysis/
+.. _pyproject.toml file: https://github.com/MDAnalysis/mdanalysis/blob/develop/package/pyproject.toml#L69
+.. _GCC documentation on -march: https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html
+.. _-mcpu: https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html
+.. _Anaconda installer: https://docs.anaconda.com/free/anaconda/install/