From 3503983bfbd070a5f13103f458fbd034a6d226cf Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 9 Feb 2021 11:04:36 +0100 Subject: [PATCH 1/2] Install: Add Python installation instructions, based on OHBM's hackathon instructions Thanks to @Remi-Gau for the suggestion and the OHBM hackathon team for the original instructions This adds mostly OS-independent installation instructions for Python, together with a more in-depth highlighting of the need for (and differences) of Python 3. It also fixes issue #638 by explicitly warning against the Windows Store version of Python, as this at the moment does not configure the /home/adina/env/handbook2/bin:/home/adina/.dotfiles/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/X11R6/bin:/usr/local/games:/usr/games:/home/adina/.local/bin:/home/adina/bin:/snap/bin appropriately. Fixes #649. --- docs/intro/installation.rst | 40 +++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst index 1aa3b918a..ea0f4d32e 100644 --- a/docs/intro/installation.rst +++ b/docs/intro/installation.rst @@ -17,8 +17,9 @@ Install DataLad The content in this chapter is largely based on the information given on the `DataLad website `_ and the `DataLad documentation `_. +Python installation instructions are largely based on instructions from the `2020 OHBM hackathon `_. -Beyond DataLad itself, the installation requires Python, :term:`Git`, and :term:`git-annex`, and may require Python's package manager ``pip`` and `p7zip/7-Zip `_. +Beyond DataLad itself, the installation requires Python 3, :term:`Git`, and :term:`git-annex`, and may require Python's package manager ``pip`` and `p7zip/7-Zip `_. The instructions below detail how to install each of these components for different common operating systems. Please `file an issue `_ @@ -32,6 +33,41 @@ exist, and they need to be installed separately, if needed. .. figure:: ../artwork/src/install.svg :width: 70% +Python 3 (all operating systems) +"""""""""""""""""""""""""""""""" + +You should make sure that you have Python 3 installed on your system. +The easiest way to do this is to open a terminal and type "python" to open a minimalistic Python session:: + + $ python + Python 3.9.1+ (default, Jan 20 2021, 14:49:22) + [GCC 10.2.1 20210110] on linux + Type "help", "copyright", "credits" or "license" for more information. + >>> + +If this fails, or reports a Python version with a leading ``2``, such as ``Python 2.7.18``, try typing ``python3`` (which some systems use to disambiguate between Python 2 and Python 3). +If this fails, too, you need to obtain a recent release of Python 3. + +If you are on Windows, please note that you should **not** install Python via the Windows store, even if it opens after you typed ``python`` as this version requires additional configurations by hand (in particular of your ``$PATH`` :term:`environment variable`. +Please instead check the Windows section at the end of the page for more convenient alternatives. + +.. findoutmore:: Python 2, Python 3, what's the difference? + + Python 2 is an outdated, in technical terms "deprecated", version of Python. + Although it still exist as the default Python version on many systems, it is no longer maintained since 2020, and thus, most software has dropped support for Python 2. + If you only run Python 2 on your system, most Python software, including DataLad, will be incompatible, and hence unusable, resulting in errors during installation and execution. + +Regardless of your operating system, we recommend installing Python via `Miniconda `_, a minimal Python installer. +To install it from the command line, run + +.. code-block:: bash + + $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest--x86_64.sh + $ bash Miniconda3-latest--x86_64.sh + +In the above call, replace ```` with an identifier for your operating system, such as "Linux" or "MacOSX" (if you are on Windows, please read the Windows-specific instructions). +During the installation, you will need to accept a license agreement (press Enter to scroll down, and type "yes" and Enter to accept), confirm the installation into the default directory, and you should respond "yes" to the prompt ``“Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]”``. +Afterwards, you can remove the installation script by running ``rm ./Miniconda3-latest-*-x86_64.sh``. Linux: (Neuro)Debian, Ubuntu, and similar systems """"""""""""""""""""""""""""""""""""""""""""""""" @@ -71,7 +107,7 @@ Linux-machines with no root access (e.g. HPC systems) """"""""""""""""""""""""""""""""""""""""""""""""""""" If you want to install DataLad on a machine you do not have root access to, DataLad -can be installed with `Miniconda `_. +can be installed with `Miniconda `__. .. code-block:: bash From a92924c85622f1d07787de9584bb36735510d383 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Wed, 10 Feb 2021 08:18:04 +0100 Subject: [PATCH 2/2] Install: Explicitly advise against uninstalling Python 2 --- docs/intro/installation.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst index ea0f4d32e..bcede57db 100644 --- a/docs/intro/installation.rst +++ b/docs/intro/installation.rst @@ -48,7 +48,7 @@ The easiest way to do this is to open a terminal and type "python" to open a min If this fails, or reports a Python version with a leading ``2``, such as ``Python 2.7.18``, try typing ``python3`` (which some systems use to disambiguate between Python 2 and Python 3). If this fails, too, you need to obtain a recent release of Python 3. -If you are on Windows, please note that you should **not** install Python via the Windows store, even if it opens after you typed ``python`` as this version requires additional configurations by hand (in particular of your ``$PATH`` :term:`environment variable`. +If you are on Windows, please note that you should **not** install Python via the Windows store, even if it opens after you typed ``python``, as this version requires additional configurations by hand (in particular of your ``$PATH`` :term:`environment variable`). Please instead check the Windows section at the end of the page for more convenient alternatives. .. findoutmore:: Python 2, Python 3, what's the difference? @@ -57,6 +57,13 @@ Please instead check the Windows section at the end of the page for more conveni Although it still exist as the default Python version on many systems, it is no longer maintained since 2020, and thus, most software has dropped support for Python 2. If you only run Python 2 on your system, most Python software, including DataLad, will be incompatible, and hence unusable, resulting in errors during installation and execution. + But does that mean that you should uninstall Python 2? + **No**. + Keep it installed, especially if you are using Linux or MacOS. + Python 2 existed for 20 years and numerous software has been written in it. + It is quite likely that some basic operating system components or legacy software on your computer is depending on it, and uninstalling a preinstalled Python 2 from your system will likely render it unusable. + Install Python 3, and have both versions coexist peacefully. + Regardless of your operating system, we recommend installing Python via `Miniconda `_, a minimal Python installer. To install it from the command line, run