✏️ Update PyMC3 Docs installation by Conda Forge

✏️ Update README.rst

Add note about pip installation

Co-authored-by: Thomas Wiecki <[email protected]>

Update README.rst

Add context to pip installation and dependencies

Co-authored-by: Thomas Wiecki <[email protected]>

Apply suggestions from code review

Co-authored-by: Thomas Wiecki <[email protected]>

✏️ README installation update

Author: CloudChaoszero

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,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
 
-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
 --------

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