Enable ReadTheDocs on v3 (#4805)

* Add readthedocs yml file
* Manually invoke building gallery instead of using it as an extension
* Bring back the gallery extension. Just create the required directories for sphinx to build tutorials and examples section
* Fixup a bug when expected static directories are already present; Simplified to use existing directories path
* Simplified relative urls handling
* Given a mention in release notes
* Add installation links to landing page
* Update pymc-examples submodule
* Fix relative links for in-depth guides

Author: Sayam753

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+sphinx:
+    configuration: docs/source/conf.py
+
+python:
+   version: 3.7
+   install:
+   - requirements: requirements-dev.txt
+   - method: pip
+     path: .
+
+
+submodules:
+    include: all
+    recursive: true

RELEASE-NOTES.md

@@ -6,6 +6,7 @@
 + `theano.printing.pydotprint` is now hotfixed upon import (see [#4594](https://github.com/pymc-devs/pymc3/pull/4594)).
 + Fix bug in the computation of the log pseudolikelihood values (SMC-ABC). (see [#4672](https://github.com/pymc-devs/pymc3/pull/4672)).
 + Fix `LKJCorr.random` method to work with `pm.sample_prior_predictive`. (see [#4780](https://github.com/pymc-devs/pymc3/pull/4780))
++ Enable documentation generation via ReadTheDocs for upcoming v3 releases. (see [#4805](https://github.com/pymc-devs/pymc3/pull/4805)).
 
 ### New Features
 + Generalized BART, bounded distributions like Binomial and Poisson can now be used as likelihoods (see [#4675](https://github.com/pymc-devs/pymc3/pull/4675), [#4709](https://github.com/pymc-devs/pymc3/pull/4709) and

docs/source/conf.py

@@ -15,6 +15,8 @@
 import os
 import sys
 
+from pathlib import Path
+
 import pymc3
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -330,3 +332,6 @@
 def setup(app):
     app.add_css_file("https://cdn.jsdelivr.net/npm/[email protected]/dist/semantic.min.css")
     app.add_css_file("default.css")
+    dir_root = Path(__file__).parent
+    for directory in html_static_path:
+        os.makedirs(str(dir_root / directory), exist_ok=True)

docs/source/index.rst

@@ -44,60 +44,60 @@
 
         <div class="ui container">
 
-        <h2 class="ui dividing header">Installation</h2>
-
-            <div class="row">
-                <div class="ui text container">
-                    <h3 class="ui header">Via conda-forge:</h3>
-
-.. code-block:: bash
-
-    conda install -c conda-forge pymc3
-
-
-.. raw:: html
-
-                    <h3 class="ui header">Latest (unstable):</h3>
+        <div class="ui vertical segment">
+            <h2 class="ui dividing header">Installation</h2>
+            <div class="ui three stackable cards">
 
-.. code-block:: bash
+                <a class="ui link card" href="https://github.com/pymc-devs/pymc3/wiki/Installation-Guide-(Linux)">
+                    <div class="content">
+                        <div class="header">Instructions for Linux</div>
+                    </div>
+                </a>
 
-    pip install git+https://github.com/pymc-devs/pymc3
+                <a class="ui link card" href="https://github.com/pymc-devs/pymc3/wiki/Installation-Guide-(MacOS)">
+                    <div class="content">
+                        <div class="header">Instructions for MacOS</div>
+                    </div>
+                </a>
 
-.. raw:: html
+                <a class="ui link card" href="https://github.com/pymc-devs/pymc3/wiki/Installation-Guide-(Windows)">
+                    <div class="content">
+                        <div class="header">Instructions for Windows</div>
+                    </div>
+                </a>
 
-                </div>
             </div>
         </div>
 
         <div class="ui vertical segment">
             <h2 class="ui dividing header">In-Depth Guides</h2>
             <div class="ui four stackable cards">
 
-                <a class="ui link card" href="/Probability_Distributions.html">
+                <a class="ui link card" href="Probability_Distributions.html">
                     <div class="content">
                         <div class="header">Probability Distributions</div>
                         <div class="description">PyMC3 includes a comprehensive set of pre-defined statistical distributions that can be used as model building blocks.
                         </div>
                     </div>
                 </a>
 
-                <a class="ui link card" href="/Gaussian_Processes.html">
+                <a class="ui link card" href="Gaussian_Processes.html">
                     <div class="content">
                         <div class="header">Gaussian Processes</div>
                         <div class="description">Sometimes an unknown parameter or variable in a model is not a scalar value or a fixed-length vector, but a function. A Gaussian process (GP) can be used as a prior probability distribution whose support is over the space of continuous functions. PyMC3 provides rich support for defining and using GPs.
                         </div>
                     </div>
                 </a>
 
-                <a class="ui link card" href="/pymc-examples/examples/variational_inference/variational_api_quickstart.html">
+                <a class="ui link card" href="pymc-examples/examples/variational_inference/variational_api_quickstart.html">
                     <div class="content">
                         <div class="header">Variational Inference</div>
                         <div class="description">Variational inference saves computational cost by turning a problem of integration into one of optimization. PyMC3's variational API supports a number of cutting edge algorithms, as well as minibatch for scaling to large datasets.
                         </div>
                     </div>
                 </a>
 
-                <a class="ui link card" href="/PyMC3_and_Theano.html">
+                <a class="ui link card" href="PyMC3_and_Theano.html">
                     <div class="content">
                         <div class="header">PyMC3 and Theano</div>
                         <div class="description">Theano is the deep-learning library PyMC3 uses to construct probability distributions and then access the gradient in order to implement cutting edge inference algorithms. More advanced models may be built by understanding this layer.

docs/source/pymc-examples

@@ -170,16 +170,23 @@ def build_gallery(srcdir, gallery):
         if basename.find(".rst") < 1:
             filename = os.path.join(source_dir, basename + ".ipynb")
             ex = NotebookGenerator(filename, target_dir)
+            url = Path(os.path.join(os.sep, gallery, ex.output_html))
+            # Need to chop off "/${gallery}/../" so as redirection works in multi versioned docs.
+            url = str(Path("..", *url.parts[3:]))
             data[basename] = {
                 "title": ex.pagetitle,
-                "url": os.path.join(os.sep, gallery, ex.output_html),
+                "url": url,
                 "thumb": os.path.basename(ex.png_path),
             }
+
         else:
             filename = basename.split(".")[0]
+            url = Path(os.path.join(os.sep, gallery, "../" + filename + ".html"))
+            # Need to chop off "/${gallery}/../" so as redirection works in multi versioned docs.
+            url = str(Path("..", *url.parts[3:]))
             data[basename] = {
                 "title": " ".join(filename.split("_")),
-                "url": os.path.join(os.sep, gallery, "../" + filename + ".html"),
+                "url": url,
                 "thumb": os.path.basename(default_png_path),
             }