Repository: pymc-devs/pymc
Pull request: Docs - Update PyMC3 Installation focus via Conda Forge
# Description
Closes #4398

* Update PyMC3 Installation focus via Conda Forge
* Re-arrange & add hierarchy for Installation Ordering
  * E.g. First PyMC3 Installation mentioned, then Theano & Arviz, respectively.

# Example
This preview was on my local machine 
<img width="937" alt="Example" src="https://user-images.githubusercontent.com/19514362/103477163-bdbeb500-4d70-11eb-8bb4-b7741d751daa.png">


Problem statement:
Update installation instructions to mention conda requirement
If you try to `pip install pymc3`, like our readme instructs, you will have a bad time on most platforms because:
* You will have a hard time linking your system compilers to theano
* It will be super slow because mkl will not be installed

So really, it is required to at least install the dependencies of theano and pymc3 via conda/conda-forge and we should update our instructions accordingly.

Hints from issue discussion:
I can take this on @twiecki.
Thanks @CloudChaoszero!

Commit message: :pencil2: Update PyMC3 Docs installation by Conda Forge

:pencil2: Update README.rst

Add note about pip installation

Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>

Update README.rst

Add context to pip installation and dependencies

Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>

Apply suggestions from code review

Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>

:pencil2: README installation update

Patch to review:
diff --git a/README.rst b/README.rst
index 1ed5f656b6..80b31e7ce0 100644
--- a/README.rst
+++ b/README.rst
@@ -77,22 +77,25 @@ and as part of `PyMCon 2020 <https://discourse.pymc.io/c/pymcon/2020talks/15>`__
 Installation
 ============
 
-The latest release of PyMC3 can be installed from PyPI using ``pip``:
+PyMC3 Installation
+------------------
 
-::
+The latest release of PyMC3 can be installed from Conda Forge (conda-forge):
 
-    pip install pymc3
+::
 
-**Note:** Running ``pip install pymc`` will install PyMC 2.3, not PyMC3,
-from PyPI.
+    conda install -c conda-forge pymc3
 
-Or via conda-forge:
+While strongly discouraged due to installation problems you could try to install PyMC3 and its dependencies via PyPI using ``pip``:
 
 ::
 
-    conda install -c conda-forge pymc3
+    pip install pymc3
 
-Plotting is done using `ArviZ <https://arviz-devs.github.io/arviz/>`__ - if you follow the installation instructions above, then it will be installed alongside ``PyMC3``.
+The reason installation via PyPI is difficult, especially on Windows and OSX, is that `Theano` requires compilation against MKL, which is difficult to set up, while Conda comes with its own compilers and MKL installation.
+.. note::
+
+    Running ``pip install pymc`` will install PyMC 2.3, not PyMC3, from PyPI.
 
 The current development branch of PyMC3 can be installed from GitHub, also using ``pip``:
 
@@ -101,8 +104,23 @@ The current development branch of PyMC3 can be installed from GitHub, also using
     pip install git+https://github.com/pymc-devs/pymc3
 
 To ensure the development branch of Theano is installed alongside PyMC3
-(recommended), you can install PyMC3 using the ``requirements.txt``
-file. This requires cloning the repository to your computer:
+(recommended), see the Theano Installation section, below.
+
+Lastly, another option is to clone the repository and install PyMC3 using
+``python setup.py install`` or ``python setup.py develop``.
+
+Theano Installation
+-------------------
+
+PyMC3 is tested on Python 3.6, 3.7, and 3.8 and depends on `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__,
+NumPy, SciPy, and pandas
+(see `requirements.txt <https://github.com/pymc-devs/pymc3/blob/master/requirements.txt>`__ for version
+information).
+
+That being said, you can install PyMC3 using the ``requirements.txt``
+file.
+
+This requires cloning the repository to your computer:
 
 ::
 
@@ -110,20 +128,17 @@ file. This requires cloning the repository to your computer:
     cd pymc3
     pip install -r requirements.txt
 
-However, if a recent version of Theano has already been installed on
-your system, you can install PyMC3 directly from GitHub.
+.. note::
+   If you already have `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__ installed, then re-install the module, as such
 
-Another option is to clone the repository and install PyMC3 using
-``python setup.py install`` or ``python setup.py develop``.
+    ``conda remove theano-pymc -y``
 
+    ``conda install -c conda-forge theano-pymc -y``
 
-Dependencies
-============
+Arviz Installation
+------------------
 
-PyMC3 is tested on Python 3.6, 3.7, and 3.8 and depends on `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__,
-NumPy, SciPy, and pandas
-(see `requirements.txt <https://github.com/pymc-devs/pymc3/blob/master/requirements.txt>`__ for version
-information).
+Plotting is done using `ArviZ <https://arviz-devs.github.io/arviz/>`__ - if you follow the installation instructions above, then it will be installed alongside ``PyMC3``.
 
 Optional
 --------
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a79fea8854..053e1962f1 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -54,13 +54,6 @@
 
     conda install -c conda-forge pymc3
 
-.. raw:: html
-
-                    <h3 class="ui header">Via pypi:</h3>
-
-.. code-block:: bash
-
-    pip install pymc3
 
 .. raw:: html
 


Code review comments:
diff_hunk: @@ -77,22 +77,25 @@ and as part of `PyMCon 2020 <https://discourse.pymc.io/c/pymcon/2020talks/15>`__
 Installation
 ============
 
-The latest release of PyMC3 can be installed from PyPI using ``pip``:
+PyMC3 Installation
+------------------
 
-::
+The latest release of PyMC3 can be installed from Conda Forge (conda-forge):
 
-    pip install pymc3
+::
 
-**Note:** Running ``pip install pymc`` will install PyMC 2.3, not PyMC3,
-from PyPI.
+    conda install -c conda-forge pymc3
 
-Or via conda-forge:
+While strongly discouraged due to installation problems you could try to install PyMC3 and its dependencies via PyPI using ``pip``:
 
 ::
 
-    conda install -c conda-forge pymc3
+    pip install pymc3
 
-Plotting is done using `ArviZ <https://arviz-devs.github.io/arviz/>`__ - if you follow the installation instructions above, then it will be installed alongside ``PyMC3``.
+The reason installation via PyPI is difficult, especially on Windows and OSX, is that `Theano` requires compilation against MKL, which is difficult to set up, while Conda comes with its own compilers and MKL installation.
path: README.rst
text: @user1:
```suggestion
The reason installation via PyPI is difficult, especially on Windows and OSX, is that ``Theano`` requires compilation against MKL, which is difficult to set up, while Conda comes with its own compilers and MKL installation.
```

diff_hunk: @@ -101,29 +104,41 @@ The current development branch of PyMC3 can be installed from GitHub, also using
     pip install git+https://github.com/pymc-devs/pymc3
 
 To ensure the development branch of Theano is installed alongside PyMC3
-(recommended), you can install PyMC3 using the ``requirements.txt``
-file. This requires cloning the repository to your computer:
+(recommended), see the Theano Installation section, below.
+
+Lastly, another option is to clone the repository and install PyMC3 using
+``python setup.py install`` or ``python setup.py develop``.
+
+Theano Installation
+-------------------
+
+PyMC3 is tested on Python 3.6, 3.7, and 3.8 and depends on `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__,
+NumPy, SciPy, and pandas
+(see `requirements.txt <https://github.com/pymc-devs/pymc3/blob/master/requirements.txt>`__ for version
+information).
+
+That being said, you can install PyMC3 using the ``requirements.txt``
+file.
+
+This requires cloning the repository to your computer:
 
 ::
 
     git clone https://github.com/pymc-devs/pymc3
     cd pymc3
     pip install -r requirements.txt
 
-However, if a recent version of Theano has already been installed on
-your system, you can install PyMC3 directly from GitHub.
+.. note::
+   If you already have `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__ installed, then re-install the module, as such
path: README.rst
text: @user1:
We should say that it now requires Theano-PyMC instead of just the old Theano, and that if the old Theano is installed, they just remove that and install Theano-PyMC via conda-forge.

@author:
@user1 Sounds great, I think I made the appropriate changes. Moreover, I changed the sub-bulletin title of the `Installation` section to be `Theano-PyMC Installation`.

Let me know what you think.