Add notebook gallery extension

Author: ColCarroll

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
 *.sw[op]
 examples/*.png
+nb_examples/
 build/*
 dist/*
 *.egg-info/

docs/source/conf.py

@@ -22,6 +22,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
+sys.path.insert(0, os.path.abspath('sphinxext'))
 
 # -- General configuration ------------------------------------------------
 
@@ -37,8 +38,10 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
     'numpydoc',
+    'nbsphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.autosectionlabel',
+    'gallery_generator',
 ]
 
 # Don't auto-generate summary for class members.
@@ -142,10 +145,9 @@
 
 html_theme_options = {
      "navbar_links": [
-         ("Home", "index"),
          ("Quickstart", "intro"),
          ("API", "api"),
-         ("Examples", "examples"),
+         ("Examples", "nb_examples/index"),
          ("Learn", "learn"),
     ],
 #     "fixed_sidebar": "false",
@@ -174,7 +176,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static', 'nb_examples/_images']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/source/index.rst

@@ -68,19 +68,19 @@
             </div>
         </div>
 
-        <div class="ui container">
-            <h2 class="ui dividing header">Licence</h2>
+        <div class="ui vertical segment">
+            <h2 class="ui dividing header">License</h2>
             <p>PyMC3 is licensed <a href="https://github.com/pymc-devs/pymc3/blob/master/LICENSE">under the Apache License, V2.</a></p>
         </div>
 
-        <div class="ui container">
+        <div class="ui vertical segment">
             <h2 class="ui dividing header">Citing PyMC3</h2>
             <p>Salvatier J., Wiecki T.V., Fonnesbeck C. (2016) Probabilistic programming in Python using PyMC3. PeerJ
                 Computer Science 2:e55 <a href="https://doi.org/10.7717/peerj-cs.55">DOI: 10.7717/peerj-cs.55</a>.</p>
             <p>See <a href="https://scholar.google.de/scholar?oi=bibs&hl=en&authuser=1&cites=6936955228135731011">Google Scholar</a> for a continuously updated list of papers citing PyMC3.</p>
         </div>
 
-        <div class="ui segment">
+        <div class="ui bottom attached segment">
             <h2 class="ui dividing header">Support and sponsors</h2>
             <p>PyMC3 is a non-profit project under NumFOCUS umbrella. If you want to support PyMC3 financially, you <a href="https://www.flipcause.com/widget/widget_home/MTE4OTc=">can donate here</a>.</p>
 

docs/source/learn.rst

@@ -39,6 +39,20 @@
 
     </div>
 
+    <h2 class="ui header">...with a video!</h2>
+    <div class="ui celled list">
+
+        <div class="item">
+            <i class="large youtube middle aligned icon"></i>
+            <div class="content">
+                <a href="https://www.youtube.com/playlist?list=PL1Ma_1DBbE82OVW8Fz_6Ts1oOeyOAiovy" class="header"> YouTube Playlist</a>
+                <div class="description">
+                    There is an actively curated playlist of PyMC3 talks on YouTube.
+                </div>
+            </div>
+        </div>
+    </div>
+
     <h2 class="ui header">...with a book!</h2>
     <div class="ui link four stackable cards">
 
@@ -144,28 +158,28 @@
 
         <div class="card">
             <div class="image">
-                <img src="https://images-na.ssl-images-amazon.com/images/I/51K33XI2I8L._SX330_BO1,204,203,200_.jpg">
+                <img src="https://dz13w8afd47il.cloudfront.net/sites/default/files/imagecache/ppv4_main_book_cover/3804OS_4958_Bayesian%20Analysis%20with%20Python.png">
             </div>
             <div class="content">
-                <div class="header">Bayesian Cognitive Modeling: A Practical Course</div>
-                <div class="meta">Michael Lee and Eric-Jan Wagenmakers</div>
+                <div class="header">Bayesian Analysis with Python</div>
+                <div class="meta">Osvaldo Martin</div>
                 <div class="description">
-                Focused on using Bayesian statistics in cognitive modeling.
+                A great introductory book written by a maintainer of PyMC3.
                 </div>
             </div>
             <table class="ui table">
                 <tbody>
                     <tr>
                         <td>
-                            <a href="https://bayesmodels.com/">
+                            <a href="https://www.packtpub.com/big-data-and-business-intelligence/bayesian-analysis-python">
                                 <i class="linkify icon"></i> Book website
                             </a>
                         </td>
                     </tr>
                     <tr>
                         <td>
-                            <a href="https://github.com/pymc-devs/resources/tree/master/BCM">
-                                <i class="linkify icon"></i> PyMC3 implementations
+                            <a href="https://github.com/aloctavodia/BAP">
+                                <i class="linkify icon"></i> Code and errata in PyMC3
                             </a>
                         </td>
                     </tr>
@@ -175,28 +189,28 @@
 
         <div class="card">
             <div class="image">
-                <img src="https://dz13w8afd47il.cloudfront.net/sites/default/files/imagecache/ppv4_main_book_cover/3804OS_4958_Bayesian%20Analysis%20with%20Python.png">
+                <img src="https://images-na.ssl-images-amazon.com/images/I/51K33XI2I8L._SX330_BO1,204,203,200_.jpg">
             </div>
             <div class="content">
-                <div class="header">Bayesian Analysis with Python</div>
-                <div class="meta">Osvaldo Martin</div>
+                <div class="header">Bayesian Cognitive Modeling: A Practical Course</div>
+                <div class="meta">Michael Lee and Eric-Jan Wagenmakers</div>
                 <div class="description">
-                A great introductory book written by a maintainer of PyMC3.
+                Focused on using Bayesian statistics in cognitive modeling.
                 </div>
             </div>
             <table class="ui table">
                 <tbody>
                     <tr>
                         <td>
-                            <a href="https://www.packtpub.com/big-data-and-business-intelligence/bayesian-analysis-python">
+                            <a href="https://bayesmodels.com/">
                                 <i class="linkify icon"></i> Book website
                             </a>
                         </td>
                     </tr>
                     <tr>
                         <td>
-                            <a href="https://github.com/aloctavodia/BAP">
-                                <i class="linkify icon"></i> Code and errata in PyMC3
+                            <a href="https://github.com/pymc-devs/resources/tree/master/BCM">
+                                <i class="linkify icon"></i> PyMC3 implementations
                             </a>
                         </td>
                     </tr>
@@ -236,7 +250,3 @@
         </div>
 
     </div>
-
-    <h2 class="ui header">...with a video!</h2>
-
-    <p> There is an <a href="https://www.youtube.com/playlist?list=PL1Ma_1DBbE82OVW8Fz_6Ts1oOeyOAiovy">actively curated playlist of PyMC3 talks</a> on YouTube.

docs/source/semantic_sphinx/layout.html

@@ -25,7 +25,9 @@
 
     <div class="ui container">
         <div class="ui large secondary pointing menu">
-            <img class="ui bottom aligned tiny image item" src="https://cdn.rawgit.com/pymc-devs/pymc3/master/docs/logos/svg/PyMC3_banner.svg" />
+            <a class="item" href="/">
+                <img class="ui bottom aligned tiny image" src="https://cdn.rawgit.com/pymc-devs/pymc3/master/docs/logos/svg/PyMC3_banner.svg" />
+            </a>
             {% if
             theme_navbar_links %} {%- for link in theme_navbar_links %} <a href="{{ pathto(*link[1:]) }}" class="item">{{
                 link[0] }}</a>
@@ -54,7 +56,9 @@ <h2>Probabilistic Programming in Python</h2>
 </div>
 
 <div class="ui container" role="main">
-    {% block body %}{% endblock %}
+    <div class="ui vertical segment">
+        {% block body %}{% endblock %}
+    </div>
 </div>
 {%- endblock %}
 

docs/source/sphinxext/gallery_generator.py

@@ -0,0 +1,195 @@
+"""
+Sphinx plugin to run generate a gallery for notebooks
+
+Modified from the seaborn project, which modified the mpld3 project.
+"""
+import base64
+import json
+import os
+import glob
+import shutil
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from matplotlib import image
+
+DOC_SRC = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+INDEX_TEMPLATE = """
+.. _{sphinx_tag}:
+
+.. title:: example_notebooks
+
+.. raw:: html
+
+    <h1 class="ui header">Example Notebooks</h1>
+    <div class="ui link six stackable cards">
+        {contents}
+    </div>
+"""
+
+
+def create_thumbnail(infile, width=275, height=275, cx=0.5, cy=0.5, border=4):
+    """Overwrites `infile` with a new file of the given size"""
+    im = image.imread(infile)
+    rows, cols = im.shape[:2]
+    size = min(rows, cols)
+    if size == cols:
+        xslice = slice(0, size)
+        ymin = min(max(0, int(cx * rows - size // 2)), rows - size)
+        yslice = slice(ymin, ymin + size)
+    else:
+        yslice = slice(0, size)
+        xmin = min(max(0, int(cx * cols - size // 2)), cols - size)
+        xslice = slice(xmin, xmin + size)
+    thumb = im[yslice, xslice]
+    thumb[:border, :, :3] = thumb[-border:, :, :3] = 0
+    thumb[:, :border, :3] = thumb[:, -border:, :3] = 0
+
+    dpi = 100
+    fig = plt.figure(figsize=(width / dpi, height / dpi), dpi=dpi)
+
+    ax = fig.add_axes([0, 0, 1, 1], aspect="auto", frameon=False, xticks=[], yticks=[])
+    ax.imshow(thumb, aspect="auto", resample=True, interpolation="bilinear")
+    fig.savefig(infile, dpi=dpi)
+    plt.close(fig)
+    return fig
+
+
+class NotebookGenerator(object):
+    """Tools for generating an example page from a file"""
+
+    def __init__(self, filename, target_dir):
+        self.basename = os.path.basename(filename)
+        self.stripped_name = os.path.splitext(self.basename)[0]
+        self.output_html = os.path.join(
+            "..", "notebooks", "{}.html".format(self.stripped_name)
+        )
+        self.image_dir = os.path.join(target_dir, "_images")
+        self.png_path = os.path.join(
+            self.image_dir, "{}.png".format(self.stripped_name)
+        )
+        with open(filename, "r") as fid:
+            self.json_source = json.load(fid)
+        self.pagetitle = self.extract_title()
+        self.default_image_loc = os.path.join(
+            os.path.dirname(DOC_SRC), "logos", "PyMC3.png"
+        )
+
+        # Only actually run it if the output RST file doesn't
+        # exist or it was modified less recently than the example
+        if not os.path.exists(self.output_html) or (
+            os.path.getmtime(self.output_html) < os.path.getmtime(filename)
+        ):
+
+            self.gen_previews()
+        else:
+            print("skipping {0}".format(filename))
+
+    def extract_preview_pic(self):
+        """By default, just uses the last image in the notebook."""
+        pic = None
+        for cell in self.json_source["cells"]:
+            for output in cell.get("outputs", []):
+                if "image/png" in output.get("data", []):
+                    pic = output["data"]["image/png"]
+        if pic is not None:
+            return base64.b64decode(pic)
+        return None
+
+    def extract_title(self):
+        for cell in self.json_source['cells']:
+            if cell["cell_type"] == "markdown":
+                rows = [row.strip() for row in cell["source"] if row.strip()]
+                for row in rows:
+                    if row.startswith("# "):
+                        return row[2:]
+        return self.basename.replace('_', ' ')
+
+    def gen_previews(self):
+        preview = self.extract_preview_pic()
+        if preview is not None:
+            with open(self.png_path, "wb") as buff:
+                buff.write(preview)
+        else:
+            shutil.copy(self.default_image_loc, self.png_path)
+        create_thumbnail(self.png_path)
+
+    def contents_entry(self):
+        return """
+.. raw:: html
+
+    <a class='card' href='./{0}'>
+        <div class="image">
+            <img src=../_static/{1}>
+        </div>
+        <div class="content">
+            <div class="header">{2}</div>
+        </div>
+    </a>
+
+        """.format(
+            self.output_html, os.path.basename(self.png_path), self.pagetitle
+        )
+
+
+def main(app):
+    working_dir = os.getcwd()
+    os.chdir(app.builder.srcdir)
+    static_dir = os.path.join(app.builder.srcdir, "_static")
+    target_dir = os.path.join(app.builder.srcdir, "nb_examples")
+    image_dir = os.path.join(app.builder.srcdir, "nb_examples/_images")
+    source_dir = os.path.abspath(
+        os.path.join(os.path.dirname(os.path.dirname(app.builder.srcdir)), "notebooks")
+    )
+
+    if not os.path.exists(static_dir):
+        os.makedirs(static_dir)
+
+    if not os.path.exists(target_dir):
+        os.makedirs(target_dir)
+
+    if not os.path.exists(image_dir):
+        os.makedirs(image_dir)
+
+    if not os.path.exists(source_dir):
+        os.makedirs(source_dir)
+
+    banner_data = []
+
+    contents = "\n\n"
+
+    # Write individual example files
+    files = sorted(glob.glob(os.path.join(source_dir, "*.ipynb")))
+    for filename in files:
+
+        ex = NotebookGenerator(filename, target_dir)
+
+        banner_data.append(
+            {
+                "title": ex.pagetitle,
+                "url": os.path.join("examples", ex.output_html),
+                "thumb": ex.png_path,
+            }
+        )
+
+        contents += ex.contents_entry()
+
+    if len(banner_data) < 10:
+        banner_data = (4 * banner_data)[:10]
+
+    # write index file
+    index_file = os.path.join(target_dir, "index.rst")
+    with open(index_file, "w") as index:
+        index.write(
+            INDEX_TEMPLATE.format(sphinx_tag="notebook_gallery", contents=contents)
+        )
+
+    os.chdir(working_dir)
+
+
+def setup(app):
+    app.connect("builder-inited", main)