Update readthedocs page (#466)

.gitignore

@@ -4,6 +4,8 @@ run_outputs*
 data
 .data
 results
+docs/source/examples/
+docs/source/tutorials/
 examples/*/processed
 examples/*/results
 examples/*/raw

docs/source/_templates/breadcrumbs.html

@@ -0,0 +1,28 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% set display_vcs_links = display_vcs_links if display_vcs_links is defined else True %}
+
+{% block breadcrumbs_aside %}
+  <li class="wy-breadcrumbs-aside">
+    {% if hasdoc(pagename) and display_vcs_links %}
+      {% if display_github %}
+        {% if check_meta and 'github_url' in meta %}
+          <!-- User defined GitHub URL -->
+          <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+        {% else %}
+          {% if 'examples/index' in pagename %}
+            <a href="https://github.com/pyro-ppl/funsor/blob/master/examples/README.rst" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% elif 'examples/' in pagename %}
+            <a href="https://github.com/pyro-ppl/funsor/blob/master/{{ pagename }}.py" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% else %}
+            <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+          {% endif %}
+        {% endif %}
+      {% elif show_source and source_url_prefix %}
+        <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
+      {% elif show_source and has_source and sourcename %}
+        <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+      {% endif %}
+    {% endif %}
+  </li>
+{% endblock %}

docs/source/conf.py

@@ -1,7 +1,9 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+import glob
 import os
+import shutil
 import sys
 
 import sphinx_rtd_theme
@@ -32,8 +34,17 @@
 
 # The short X.Y version
 version = u"0.0"
+
+if "READTHEDOCS" not in os.environ:
+    # if developing locally, use funsor.__version__ as version
+    from funsor import __version__  # noqaE402
+
+    version = __version__
+
+    html_context = {"github_version": "master"}
+
 # The full version, including alpha/beta/rc tags
-release = u"0.0"
+release = version
 
 
 # -- General configuration ---------------------------------------------------
@@ -46,11 +57,13 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "nbsphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
+    "sphinx_gallery.gen_gallery",
 ]
 
 # Disable documentation inheritance so as to avoid inheriting
@@ -76,7 +89,13 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".ipynb"]
+
+# do not execute cells
+nbsphinx_execute = "never"
+
+# Don't add .txt suffix to source files:
+html_sourcelink_suffix = ""
 
 # The master toctree document.
 master_doc = "index"
@@ -91,7 +110,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = []
+exclude_patterns = [".ipynb_checkpoints", "examples/*ipynb", "examples/*py"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -100,6 +119,73 @@
 # do not prepend module name to functions
 add_module_names = False
 
+
+# This is processed by Jinja2 and inserted before each notebook
+nbsphinx_prolog = r"""
+{% set docname = 'tutorials/' + env.doc2path(env.docname, base=None).split('/')[-1] %}
+:github_url: https://github.com/pyro-ppl/funsor/blob/master/{{ docname }}
+
+.. raw:: html
+
+    <div class="admonition note">
+      Interactive online version:
+      <span style="white-space: nowrap;">
+        <a href="https://colab.research.google.com/github/pyro-ppl/funsor/blob/{{ env.config.html_context.github_version }}/{{ docname }}">
+          <img alt="Open In Colab" src="https://colab.research.google.com/assets/colab-badge.svg"
+            style="vertical-align:text-bottom">
+        </a>
+      </span>
+    </div>
+"""  # noqa: E501
+
+
+# -- Copy notebook files
+# NB: tutorials and examples can be added to `index.rst` file using the paths
+#     tutorials/foo
+#     examples/foo
+# without extensions .ipynb or .py
+# TODO: find a solution for an example subfolder, e.g. examples/mixed_hmm folder
+#
+# To add thumbnail images for tutorials/examples in funsor docs, using
+# .. nbgallery:: instead of .. toctree:: and add png thumnail images
+# with corresponding names in _static/img/tutorials or _static/img/examples folders.
+# For example, we can add minipyro.png to _static/img/examples/ folder.
+
+if not os.path.exists("tutorials"):
+    os.makedirs("tutorials")
+
+for src_file in glob.glob("../../tutorials/*.ipynb"):
+    dst_file = os.path.join("tutorials", src_file.split("/")[-1])
+    shutil.copy(src_file, "tutorials/")
+
+
+# -- Convert scripts to notebooks
+
+sphinx_gallery_conf = {
+    "examples_dirs": ["../../examples"],
+    "gallery_dirs": ["examples"],
+    # only execute files beginning with plot_
+    "filename_pattern": "/plot_",
+    # 'ignore_pattern': '(minipyro|__init__)',
+    # not display Total running time of the script because we do not execute it
+    "min_reported_time": 1,
+}
+
+
+# -- Add thumbnails images
+
+nbsphinx_thumbnails = {}
+
+for src_file in glob.glob("../../tutorials/*.ipynb") + glob.glob("../../examples/*.py"):
+    toctree_path = "tutorials/" if src_file.endswith("ipynb") else "examples/"
+    filename = os.path.splitext(src_file.split("/")[-1])[0]
+    png_path = "_static/img/" + toctree_path + filename + ".png"
+    # use Pyro logo if not exist png file
+    if not os.path.exists(png_path):
+        png_path = "_static/img/pyro_logo_wide.png"
+    nbsphinx_thumbnails[toctree_path + filename] = png_path
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -157,7 +243,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "Funsor.tex", u"Funsor Documentation", u"Uber AI Labs", "manual"),
+    (master_doc, "Funsor.tex", u"Funsor Documentation", u"Uber AI Labs", "manual")
 ]
 
 # -- Options for manual page output ------------------------------------------
@@ -180,7 +266,7 @@
         "Funsor",
         "Functional analysis + tensors + symbolic algebra.",
         "Miscellaneous",
-    ),
+    )
 ]
 
 

docs/source/index.rst

@@ -32,6 +32,20 @@ Funsor is a tensor-like library for functions and distributions
    minipyro
    einsum
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials and Examples
+   :name: tutorials-and-examples
+
+   examples/discrete_hmm
+   examples/eeg_slds
+   examples/kalman_filter
+   examples/minipyro
+   examples/pcfg
+   examples/sensor
+   examples/slds
+   examples/vae
+
 
 Indices and tables
 ==================

examples/README.rst

@@ -0,0 +1,5 @@
+Code Examples
+=============
+
+Please check out `Sphinx-Gallery syntax <https://sphinx-gallery.github.io/stable/syntax.html>`_
+for how to structure Python scripts to generate nicely rendered example pages.

examples/discrete_hmm.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: Discrete HMM
+=====================
+
+"""
+
 import argparse
 from collections import OrderedDict
 

examples/eeg_slds.py

@@ -2,6 +2,9 @@
 # SPDX-License-Identifier: Apache-2.0
 
 """
+Example: Switching Linear Dynamical System EEG
+==============================================
+
 We use a switching linear dynamical system [1] to model a EEG time series dataset.
 For inference we use a moment-matching approximation enabled by
 `funsor.interpretation(funsor.terms.moment_matching)`.
@@ -10,6 +13,7 @@
 
 [1] Anderson, B., and J. Moore. "Optimal filtering. Prentice-Hall, Englewood Cliffs." New Jersey (1979).
 """
+
 import argparse
 import time
 from collections import OrderedDict

examples/kalman_filter.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: Kalman Filter
+======================
+
+"""
+
 import argparse
 
 import torch

examples/minipyro.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: Mini Pyro
+==================
+
+"""
+
 import argparse
 
 import torch

examples/mixed_hmm/model.py

@@ -24,10 +24,7 @@ def __init__(self, config):
     def initialize_params(self):
 
         # dictionary of guide random effect parameters
-        params = {
-            "eps_g": {},
-            "eps_i": {},
-        }
+        params = {"eps_g": {}, "eps_i": {}}
 
         N_state = self.config["sizes"]["state"]
 
@@ -153,8 +150,7 @@ def initialize_params(self):
             )
 
             params["eps_g"]["scale"] = Tensor(
-                torch.ones((N_state, N_state)),
-                OrderedDict([("y_prev", Bint[N_state])]),
+                torch.ones((N_state, N_state)), OrderedDict([("y_prev", Bint[N_state])])
             )
 
         # initialize individual-level random effect parameters
@@ -164,12 +160,7 @@ def initialize_params(self):
             params["e_i"]["probs"] = Tensor(
                 pyro.param(
                     "probs_e_i",
-                    lambda: torch.randn(
-                        (
-                            N_c,
-                            N_v,
-                        )
-                    ).abs(),
+                    lambda: torch.randn((N_c, N_v)).abs(),
                     constraint=constraints.simplex,
                 ),
                 OrderedDict([("g", Bint[N_c])]),  # different value per group
@@ -329,8 +320,7 @@ def __call__(self):
 
         # initialize gamma to uniform
         gamma = Tensor(
-            torch.zeros((N_state, N_state)),
-            OrderedDict([("y_prev", Bint[N_state])]),
+            torch.zeros((N_state, N_state)), OrderedDict([("y_prev", Bint[N_state])])
         )
 
         N_v = self.config["sizes"]["random"]

examples/pcfg.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: PCFG
+=============
+
+"""
+
 import argparse
 import math
 from collections import OrderedDict

examples/sensor.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: Biased Kalman Filter
+=============================
+
+"""
+
 import argparse
 import itertools
 import math

examples/slds.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: Switching Linear Dynamical System
+==========================================
+
+"""
+
 import argparse
 
 import torch
@@ -19,10 +25,7 @@ def main(args):
     )
     trans_noise = funsor.Tensor(
         torch.tensor(
-            [
-                0.1,  # low noise component
-                1.0,  # high noisy component
-            ],
+            [0.1, 1.0],  # low noise component  # high noisy component
             requires_grad=True,
         )
     )

examples/vae.py

@@ -1,6 +1,12 @@
 # Copyright Contributors to the Pyro project.
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Example: VAE MNIST
+==================
+
+"""
+
 import argparse
 import os
 from collections import OrderedDict