Docs - Update PyMC3 Installation focus via Conda Forge (#4401)

* ✏️ 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 * Update README.rst * ✏️ Focus on Theano-PyMC3 instead of Theano for installation * Update README.rst * Update README.rst Co-authored-by: Thomas Wiecki <[email protected]>
pymc-devs · Jan 5, 2021 · aabec02 · aabec02
1 parent 982bb4d
commit aabec02
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 28 deletions.
diff --git a/README.rst b/README.rst
@@ -77,53 +77,74 @@ 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``:
 
 ::
 
     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:
+Make sure to install the `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__ version that is pegged in ``PyMC3``'s ``requirements.txt``.
+For more information, see the `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__ 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-PyMC Installation
+------------------------
+
+PyMC3 is tested on Python 3.6, 3.7, and 3.8 and depends on NumPy, SciPy, and pandas
+(see `requirements.txt <https://github.com/pymc-devs/pymc3/blob/master/requirements.txt>`__ for version
+information).
+
+Moreover, as of Late 2020, PyMC3 now requires `Theano-PyMC <https://github.com/pymc-devs/Theano-PyMC>`__ instead of `Theano <https://github.com/Theano/Theano>`__.
+
+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::
 
-Another option is to clone the repository and install PyMC3 using
-``python setup.py install`` or ``python setup.py develop``.
+   * If you have Theano installed, please remove it and install Theano-PyMC via Conda Forge, seen below:
 
+    ``conda remove theano``
 
-Dependencies
-============
+   * If you have an outdated version of Theano-PyMC, then re-install the module via Conda Forge:
 
-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).
+    ``conda remove theano-pymc -y``
+
+    ``conda install -c conda-forge theano-pymc -y``
+
+Arviz Installation
+------------------
+
+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
@@ -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