Repository: sktime/sktime
Pull request: rework of installation guidelines
This is a rework of the installation guidelines.

They have grown a bit organically and were all over the place.

Was originally going to write the developer guidelines, but I found that these needed a cleaning first.

Problem statement:
[DOC]Install requirements for WSL2 in installation guide
#### Describe the issue linked to the documentation
It has come to my attention that in order to run `sktime` under WSL2, we should follow the Ubuntu linux instructions.

<!--
Tell us about the confusion introduced in the documentation.
-->
We should include a `..note` directive in the windows instructions pointing to the linux ones for users of WSL2 as their platform.

Hints from issue discussion:
Closing for #1010
well, it hasn't been merged yet, so let's reopen but attach to the new PR, so it closes whan that gets merged.

Commit message: typos

Patch to review:
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 92a8ae555a8..81d27df0f83 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -3,43 +3,114 @@
 Installation
 ============
 
-sktime is available via PyPI using:
+``sktime`` requires an environment with python version 3.6 or higher.
+
+Release versions
+----------------
+
+For frequent issues with installation, consult the `Release versions - troubleshooting`_ section.
+
+Installing sktime from PyPI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``sktime`` releases are available via PyPI and can be installed via ``pip`` using:
 
 .. code-block:: bash
 
     pip install sktime
 
-But note that the package is actively being developed and currently not feature stable.
+This will install ``sktime`` with core dependencies, excluding interfaced packages.
 
+To install ``sktime`` with maximum dependencies, including all interfaced packages, install with the ``all_extras`` modifier:
 
-Development version
--------------------
-To install the latest development version of sktime, follow these steps:
+.. code-block:: bash
 
-1. Download the repository: :code:`git clone https://github.com/alan-turing-institute/sktime.git`
-2. Move into the root directory of the repository: :code:`cd sktime`
-3. Make sure you are on the main branch: :code:`git checkout main`
-4. Make sure your local version is up-to-date: :code:`git pull`
-5. Build package from source using: :code:`pip install --editable .` Please read below for more detailed instructions for specific operating systems.
+    pip install sktime[all_extras]
 
-Building sktime from source also requires
 
-- Cython >= 0.28.5 (available through :code:`pip install cython`)
-- OpenMP (see below for instructions)
+Installing sktime from conda
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+``sktime`` releases are available via ``conda`` from ``conda-forge``.
+They can be installed via ``conda`` using:
 
-   It is possible to build sktime without OpenMP support by setting the
-   ``SKTIME_NO_OPENMP`` environment variable (before cythonization). This is
-   not recommended since it will force some estimators to run in sequential
-   mode and their ``n_jobs`` parameter will be ignored.
+.. code-block:: bash
+
+    conda install -c conda-forge sktime
+
+This will install ``sktime`` with core dependencies, excluding interfaced packages.
+
+To install ``sktime`` with maximum dependencies, including all interfaced packages, install with the ``all_extras`` modifier:
+
+.. code-block:: bash
+
+    conda install -c conda-forge sktime[all_extras]
+
+
+Release versions - troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Module not found
+""""""""""""""""
+
+The most frequent reason for "module not found" errors is installing ``sktime`` with minimum dependencies
+and using an estimator which interfaces a packages that has not been installed in the environment.
+To resolve this, install the missing package, or install ``sktime`` with maximum dependencies (see above).
+
+
+Facebook prophet
+""""""""""""""""
+
+A frequent issue arises with installation of facebook prophet when installing via ``pip``, especially on Windows systems.
+
+Potential workaround no.1, install manually via ``conda-forge``:
+
+.. code-block:: bash
+
+    conda install -c conda-forge pystan
+    conda install -c conda-forge prophet
+
+The remaining packages can be installed via ``pip`` or ``conda``.
 
-To run our tests and generate our documentation, you need to follow a few extra steps as described in our section on :ref:`contributing`.
+Potential workaround no.2, install ``pystan`` with ``no-cache`` parameter:
 
-Retrieving other stable versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: bash
+
+    pip install pystan --no-cache
+
+Potential workaround no.3, if on Windows: use WSL (Windows Subsystem for Linux), see end of section `Windows 8.1 and higher`_.
+
+
+numpy or C related issues
+"""""""""""""""""""""""""
+
+``numpy`` and C related errors on Windows based systems are potentially resolved by installing Build Tools for Visual Studio 2019 or 2017.
+
+
+Development versions
+--------------------
+To install the the latest development version of ``sktime``, or earlier versions, the sequence of steps is as follows:
+
+Step 1 - ``git`` clone the ``sktime`` repository, the latest version or an earlier version.
+Step 2 - ensure build requirements are satisfied
+Step 3 - ``pip`` install the package from a ``git`` clone, with the ``editable`` parameter.
+
+Detail instructions for all steps are given below.
+For brevity, we discuss steps 1 and 3 first; step 2 is discussed at the end, as it will depend on the operating system.
+
+Step 1 - git cloning the repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``sktime`` repository should be cloned to a local directory, using a graphical user interface, or the command line.
+
+Using the ``git`` command line, the sequence of commands to install the latest version is as follows:
+
+1. Clone the repository: :code:`git clone https://github.com/alan-turing-institute/sktime.git`
+2. Move into the root directory of the local clone: :code:`cd sktime`
+3. Make sure you are on the main branch: :code:`git checkout main`
+4. Make sure your local version is up-to-date: :code:`git pull`
 
-If you want to build a previous version, you can run:
+To build a previous version, replace line 3 with:
 
 .. code-block:: bash
 
@@ -49,27 +120,26 @@ This will checkout the code for that particular version. To see which versions a
 
 You can also `download <https://github.com/alan-turing-institute/sktime/releases>`_ a zip archive of the version from GitHub.
 
-Building from source
-~~~~~~~~~~~~~~~~~~~~
 
-Once you have all the build requirements installed (see below for details),
-you can build and install the package in the following way.
+Step 3 - building sktime from source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you run the development version, it is cumbersome to reinstall the
-package each time you update the sources. Therefore it's recommended that you
-install in editable mode, which allows you to edit the code in-place. This
-builds the extension in place and creates a link to the development directory
-(see `the pip docs <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_):
+For a static install of ``sktime`` from source, navigate to the local clone's root directory and type:
 
 .. code-block:: bash
 
-    pip install --editable .
+    pip install .
 
-.. note::
+Alternatively, the ``.`` may be replaced with a full or relative path to the root directlry.
+
+For a developer install that updates the package each time the local source code is changed, install ``sktime`` in editable mode, via:
+
+.. code-block:: bash
+
+    pip install --editable .
 
-    This is fundamentally similar to using the command ``python setup.py develop``
-    (see `the setuptool docs <https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode>`_).
-    It is however preferred to use pip.
+This allows editing and extending the code in-place. See also
+`the pip reference on editable installs <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_).
 
 .. note::
 
@@ -84,37 +154,35 @@ builds the extension in place and creates a link to the development directory
     Compiled extensions are Cython files (ending in `.pyx` or `.pxd`).
 
 
-Mac OSX
-*******
+Step 2 - build requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The default C compiler, Apple-clang, on Mac OSX does not directly support
-OpenMP. The first solution to build sktime is to install another C
-compiler such as gcc or llvm-clang. Another solution is to enable OpenMP
-support on the default Apple-clang. In the following we present how to
-configure this second option.
+Building sktime from source requires, in addition to step 1:
 
-You first need to install the OpenMP library:
+- Cython >= 0.28.5 (available through :code:`pip install cython`)
+- OpenMP and a working C compiler (see below for instructions)
 
-.. code-block:: bash
+.. note::
 
-    brew install libomp
+   It is possible to build sktime without OpenMP support by setting the
+   ``SKTIME_NO_OPENMP`` environment variable (before cythonization). This is
+   not recommended since it will force some estimators to run in sequential
+   mode and their ``n_jobs`` parameter will be ignored.
 
-Then you need to set the following environment variables:
+For the advanced developer set-up which includes tests and documentation,
+see the advanced developer documentation in :ref:`contributing`.
 
-.. code-block:: bash
+The following sections describe how to satisfy the build requirements, by operating system.
+We currently support:
 
-    export CC=/usr/bin/clang
-    export CXX=/usr/bin/clang++
-    export CPPFLAGS="$CPPFLAGS -Xpreprocessor -fopenmp"
-    export CFLAGS="$CFLAGS -I/usr/local/opt/libomp/include"
-    export CXXFLAGS="$CXXFLAGS -I/usr/local/opt/libomp/include"
-    export LDFLAGS="$LDFLAGS -L/usr/local/opt/libomp/lib -lomp"
-    export DYLD_LIBRARY_PATH=/usr/local/opt/libomp/lib
+- `FreeBSD`_
+- `Mac OSX`_
+- `Unix-like OS`_
+- `Windows 8.1 and higher`_
 
-Finally you can build the package using the standard command.
 
 FreeBSD
-*******
+"""""""
 
 The clang compiler included in FreeBSD 12.0 and 11.2 base systems does not
 include OpenMP support. You need to install the `openmp` library from packages
@@ -141,11 +209,38 @@ For the upcoming FreeBSD 12.1 and 11.3 versions, OpenMP will be included in
 the base system and these steps will not be necessary.
 
 
-Installing build dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Mac OSX
+"""""""
+
+The default C compiler, Apple-clang, on Mac OSX does not directly support
+OpenMP. The first solution to build sktime is to install another C
+compiler such as gcc or llvm-clang. Another solution is to enable OpenMP
+support on the default Apple-clang. In the following we present how to
+configure this second option.
+
+You first need to install the OpenMP library:
+
+.. code-block:: bash
+
+    brew install libomp
+
+Then you need to set the following environment variables:
+
+.. code-block:: bash
+
+    export CC=/usr/bin/clang
+    export CXX=/usr/bin/clang++
+    export CPPFLAGS="$CPPFLAGS -Xpreprocessor -fopenmp"
+    export CFLAGS="$CFLAGS -I/usr/local/opt/libomp/include"
+    export CXXFLAGS="$CXXFLAGS -I/usr/local/opt/libomp/include"
+    export LDFLAGS="$LDFLAGS -L/usr/local/opt/libomp/lib -lomp"
+    export DYLD_LIBRARY_PATH=/usr/local/opt/libomp/lib
+
+Finally you can build the package using the standard command.
+
 
-Linux
-*****
+Unix-like OS
+""""""""""""
 
 Installing from source without conda requires you to have installed the
 sktime runtime dependencies, Python development headers and a working
@@ -181,8 +276,9 @@ On Red Hat and clones (e.g. CentOS), install the dependencies using:
     `scipy installation instructions
     <https://docs.scipy.org/doc/scipy/reference/building/linux.html>`_.
 
-Windows
-*******
+
+Windows 8.1 and higher
+""""""""""""""""""""""
 
 To build sktime on Windows you need a working C/C++ compiler in
 addition to numpy, scipy and setuptools.
@@ -238,35 +334,40 @@ If you run into a problem installing the development version and are using Anaco
 
 In step 5, you may optionally install the packages in build_tools/requirements.txt that are available from Anaconda's default channels or `Conda-Forge <https://anaconda.org/conda-forge>`_ via Conda. Any remaining packages can be added via pip.
 
-Building binary packages and installers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
 
-The ``.whl`` package and ``.exe`` installers can be built with:
+    It is possible to use `MinGW <http://www.mingw.org>`_ (a port of GCC to Windows
+    OS) as an alternative to MSVC for 32-bit Python. Not that extensions built with
+    mingw32 can be redistributed as reusable packages as they depend on GCC runtime
+    libraries typically not installed on end-users environment.
 
-.. code-block:: bash
+    To force the use of a particular compiler, pass the ``--compiler`` flag to the
+    build step:
 
-    pip install wheel
-    python setup.py bdist_wheel bdist_wininst
+    .. code-block:: bash
+
+        python setup.py build --compiler=my_compiler install
+
+    where ``my_compiler`` should be one of ``mingw32`` or ``msvc``.
 
-The resulting packages are generated in the ``dist/`` folder.
 
+.. note::
+
+    Another option under Windows is to follow the instructions for `Unix-like OS`_, using the Windows Subsystem for Linux (WSL).
+    For installing WSL, follow the instructions `here <https://docs.microsoft.com/en-us/windows/wsl/install-win10#step-2---check-requirements-for-running-wsl-2>`_.
 
-Using an alternative compiler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is possible to use `MinGW <http://www.mingw.org>`_ (a port of GCC to Windows
-OS) as an alternative to MSVC for 32-bit Python. Not that extensions built with
-mingw32 can be redistributed as reusable packages as they depend on GCC runtime
-libraries typically not installed on end-users environment.
+Building binary packages and installers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To force the use of a particular compiler, pass the ``--compiler`` flag to the
-build step:
+The ``.whl`` package and ``.exe`` installers can be built with:
 
 .. code-block:: bash
 
-    python setup.py build --compiler=my_compiler install
+    pip install wheel
+    python setup.py bdist_wheel bdist_wininst
 
-where ``my_compiler`` should be one of ``mingw32`` or ``msvc``.
+The resulting packages are generated in the ``dist/`` folder.
 
 
 References


Code review comments:
diff_hunk: @@ -3,43 +3,114 @@
 Installation
 ============
 
-sktime is available via PyPI using:
+``sktime`` requires an environment with python version 3.6 or higher.
+
+Release versions
+----------------
+
+For frequent issues with installation, consult the `Release versions - troubleshooting`_ section.
+
+Installing sktime from PyPI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``sktime`` releases are available via PyPI and can be installed via ``pip`` using:
 
 .. code-block:: bash
 
     pip install sktime
 
-But note that the package is actively being developed and currently not feature stable.
+This will install ``sktime`` with core dependencies, excluding interfaced packages.
 
+To install ``sktime`` with maximum dependencies, including all interfaced packages, install with the ``all_extras`` modifier:
 
-Development version
--------------------
-To install the latest development version of sktime, follow these steps:
+.. code-block:: bash
 
-1. Download the repository: :code:`git clone https://github.com/alan-turing-institute/sktime.git`
-2. Move into the root directory of the repository: :code:`cd sktime`
-3. Make sure you are on the main branch: :code:`git checkout main`
-4. Make sure your local version is up-to-date: :code:`git pull`
-5. Build package from source using: :code:`pip install --editable .` Please read below for more detailed instructions for specific operating systems.
+    pip install sktime[all_extras]
 
-Building sktime from source also requires
 
-- Cython >= 0.28.5 (available through :code:`pip install cython`)
-- OpenMP (see below for instructions)
+Installing sktime from conda
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+``sktime`` releases are available via ``conda`` from ``conda-forge``.
+They can be installed via ``conda`` using:
 
-   It is possible to build sktime without OpenMP support by setting the
-   ``SKTIME_NO_OPENMP`` environment variable (before cythonization). This is
-   not recommended since it will force some estimators to run in sequential
-   mode and their ``n_jobs`` parameter will be ignored.
+.. code-block:: bash
+
+    conda install -c conda-forge sktime
+
+This will install ``sktime`` with core dependencies, excluding interfaced packages.
+
+To install ``sktime`` with maximum dependencies, including all interfaced packages, install with the ``all_extras`` modifier:
+
+.. code-block:: bash
+
+    conda install -c conda-forge sktime[all_extras]
path: docs/source/installation.rst
text: @user1:
Does this work with conda? 

@author:
it actually doesn't - thanks for pointing this out.
an installation starts (due to flexible solve), but `conda` handles package variants and extras differently, so this will not work.

This looks like the latest on the topic?
https://github.com/conda/conda/issues/7502

In any case, what should I write then: if you want all optional dependencies easily, use `pip`, not `conda`?

@user1:
Not sure, the requirements management isn't ideal at the moment. The `pip install sktime[extras]` syntax also isn't very widely known. It would be nice to have a single conda environment yaml file that people can install. Alternatively, you install the conda environment, activate it and then from inside that environment, use the pip install command. 

@author:
perhaps conda meta-packages are the way to go?

@author:
anyway, fixed the reference

diff_hunk: @@ -3,43 +3,114 @@
 Installation
 ============
 
-sktime is available via PyPI using:
+``sktime`` requires an environment with python version 3.6 or higher.
path: docs/source/installation.rst
text: @user1:
```suggestion
``sktime`` requires an environment with python version 3.6, 3.7 or 3.8.
```

@author:
that's not what `setup.py` says, does it?

@user1:
As far as I can see `setup.py` only gives you the minimum but not the maximum version requirement. I think this section also isn't about installing via `setup.py` but [availability of precompiled wheels](https://pypi.org/simple/sktime/) on PyPI. Perhaps add the link to https://pypi.org/simple/sktime/ for people to see which wheel we currently provide?

@author:
I think you can specify `max_python_version`?

@author:
extended the paragraph for that

diff_hunk: @@ -238,35 +334,40 @@ If you run into a problem installing the development version and are using Anaco
 
 In step 5, you may optionally install the packages in build_tools/requirements.txt that are available from Anaconda's default channels or `Conda-Forge <https://anaconda.org/conda-forge>`_ via Conda. Any remaining packages can be added via pip.
 
-Building binary packages and installers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
 
-The ``.whl`` package and ``.exe`` installers can be built with:
+    It is possible to use `MinGW <http://www.mingw.org>`_ (a port of GCC to Windows
+    OS) as an alternative to MSVC for 32-bit Python. Not that extensions built with
+    mingw32 can be redistributed as reusable packages as they depend on GCC runtime
+    libraries typically not installed on end-users environment.
 
-.. code-block:: bash
+    To force the use of a particular compiler, pass the ``--compiler`` flag to the
+    build step:
 
-    pip install wheel
-    python setup.py bdist_wheel bdist_wininst
+    .. code-block:: bash
+
+        python setup.py build --compiler=my_compiler install
+
+    where ``my_compiler`` should be one of ``mingw32`` or ``msvc``.
 
-The resulting packages are generated in the ``dist/`` folder.
 
+.. note::
+
+    Another option under Windows is to follow the instructions for `Unix-like OS`_, using the Windows Subsystem for Linux (WSL).
+    For installing WSL, follow the instructions `here <https://docs.microsoft.com/en-us/windows/wsl/install-win10#step-2---check-requirements-for-running-wsl-2>`_.
 
-Using an alternative compiler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is possible to use `MinGW <http://www.mingw.org>`_ (a port of GCC to Windows
-OS) as an alternative to MSVC for 32-bit Python. Not that extensions built with
-mingw32 can be redistributed as reusable packages as they depend on GCC runtime
-libraries typically not installed on end-users environment.
+Building binary packages and installers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To force the use of a particular compiler, pass the ``--compiler`` flag to the
-build step:
+The ``.whl`` package and ``.exe`` installers can be built with:
 
 .. code-block:: bash
 
-    python setup.py build --compiler=my_compiler install
+    pip install wheel
+    python setup.py bdist_wheel bdist_wininst
path: docs/source/installation.rst
text: @user1:
`bdist_wininst` has been deprecated since Python 3.8, not sure if we still want to mention it here

@author:
well, I just copied what was there. What would you suggest as a change?

@user1:
Don't have a strong preference, I'd say we stick with wheels, so:
```suggestion
    python setup.py bdist_wheel
```
If people want other precompiled files, they can look up the `setup.py` documentation for that.