Add example gallery to docs (#1150)

* Add example gallery

* Add example gallery

* Update rtd environment

* Fix typo in `generate_gallery.py`

* Add graph rewriting tutorial to examples

* Add default gallery image

* Fix default image path

* Add default image

* Add scan tutorial example

* Add header links to github/colab/binder

Add ablog with tags, authors, and categories

Modify example notebooks

* Update license and package name in footer

Delete placeholder notebook

* Delete docs for `sandbox` module

* rename `pytensor.tensor.var._tensor_py_operators` -> `pytensor.tensor.variable._tensor_py_operators`

* Fix underline lengths

* Remove reference to depreciated functions

* Add end of file newline

* Remove references to sandbox

* Try adding sitemap and robots.txt

* pre-commit

* Add cross-references and fix formatting

* Fix cross-reference

Author: jessegrabowski

doc/.templates/nb-badges.html

@@ -0,0 +1,24 @@
+{% if pagename in ablog %}
+
+<!-- Generate correct links and render github/binder/colab badges -->
+{% set gh_basepath =  github_user + '/' + github_repo + '/blob/' + github_version + '/' %}
+{% set encoded_base =  github_user + '%252F' + github_repo  %}
+{% set gh_binder = github_user + '/' + github_repo + '/' + github_version %}
+{% set doc_path_aux = doc_path | trim('/') %}
+{% set file_path = doc_path_aux + '/' + pagename + ".ipynb" %}
+{% set encoded_path = file_path | replace("/", "%252F") %}
+
+
+<div class="sd-text-right">
+  <p>
+    <a href="{{ github_url + '/' + gh_basepath + file_path }}", role="button" target="_blank">
+    <img src="{{ pathto('_static/github.svg', 1) }}" alt="View On GitHub"></a>
+
+    <a href="{{ 'https://mybinder.org/v2/gh/' + sandbox_repo + '?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252F' + encoded_base + '%26urlpath%3Dtree%252F' + github_repo + '%252F' + encoded_path + '%26branch%3D' + github_version }}" target="_blank">
+    <img src="{{ pathto('_static/binder.svg', 1) }}" alt="Open In Binder"></a>
+
+    <a href="{{ 'https://colab.research.google.com/github/' + gh_basepath + file_path }}" target="_blank">
+    <img src="{{ pathto('_static/colab.svg', 1) }}" alt="Open In Colab"/></a>
+  </p>
+</div>
+{% endif %}

doc/.templates/rendered_citation.html

@@ -0,0 +1,13 @@
+<!-- continuation of examples/page_footer.md -->
+{% if pagename in ablog %}
+  {% set post = ablog[pagename] %}
+    {% for coll in post.author %}
+      {% if coll|length %}
+        {{ coll }}
+        {% if loop.index < post.author | length %},{% endif %}
+      {% else %}
+        {{ coll }}
+        {% if loop.index < post.author | length %},{% endif %}
+      {% endif %}
+    {% endfor %}. "{{ title.split(' — ')[0] }}". In: <i>Pytensor Examples</i>. Ed. by Pytensor Team. <!-- DOI: <a href={{ doi_url }}>{{ doi_code }}</a>  -->
+{% endif %}

doc/blog.md

@@ -0,0 +1,7 @@
+---
+orphan: true
+---
+
+# Recent updates
+
+<!-- auto generated by ablog so it's empty -->

doc/conf.py

@@ -1,31 +1,13 @@
-# pytensor documentation build configuration file, created by
-# sphinx-quickstart on Tue Oct  7 16:34:06 2008.
-#
-# This file is execfile()d with the current directory set to its containing
-# directory.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed
-# automatically).
-#
-# All configuration values have a default value; values that are commented out
-# serve to show the default value.
-
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use Path.absolute to make it
-# absolute, like shown here.
-# sys.path.append(str(Path("some/directory").absolute()))
-
 import os
 import inspect
 import sys
 import pytensor
+from pathlib import Path
+
+sys.path.insert(0, str(Path("..").resolve() / "scripts"))
 
 # General configuration
 # ---------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
@@ -34,9 +16,22 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
     "sphinx_design",
-    "sphinx.ext.intersphinx"
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    "ablog",
+    "myst_nb",
+    "generate_gallery",
+    "sphinx_sitemap",
 ]
 
+# Don't auto-generate summary for class members.
+numpydoc_show_class_members = False
+autosummary_generate = True
+autodoc_typehints = "none"
+remove_from_toctrees = ["**/classmethods/*"]
+
+
 intersphinx_mapping = {
     "jax": ("https://jax.readthedocs.io/en/latest", None),
     "numpy": ("https://numpy.org/doc/stable", None),
@@ -92,6 +87,7 @@
 # List of directories, relative to source directories, that shouldn't be
 # searched for source files.
 exclude_dirs = ["images", "scripts", "sandbox"]
+exclude_patterns = ['page_footer.md', '**/*.myst.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -115,19 +111,15 @@
 # Options for HTML output
 # -----------------------
 
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-# html_style = 'default.css'
-# html_theme = 'sphinxdoc'
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "pymc_sphinx_theme"
+html_logo = "images/PyTensor_RGB.svg"
+
+html_baseurl = "https://pytensor.readthedocs.io"
+sitemap_url_scheme = f"{{lang}}{rtd_version}/{{link}}"
 
-# html4_writer added to Fix colon & whitespace misalignment
-# https://github.com/readthedocs/sphinx_rtd_theme/issues/766#issuecomment-513852197
-# https://github.com/readthedocs/sphinx_rtd_theme/issues/766#issuecomment-629666319
-# html4_writer = False
 
-html_logo = "images/PyTensor_RGB.svg"
-html_theme = "pymc_sphinx_theme"
 html_theme_options = {
     "use_search_override": False,
     "icon_links": [
@@ -156,15 +148,27 @@
             "type": "fontawesome",
         },
     ],
+    "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink", "donate"],
+    "navbar_start": ["navbar-logo"],
+    "article_header_end": ["nb-badges"],
+    "article_footer_items": ["rendered_citation.html"],
 }
 html_context = {
+    "github_url": "https://github.com",
     "github_user": "pymc-devs",
     "github_repo": "pytensor",
-    "github_version": "main",
+    "github_version": version if "." in rtd_version else "main",
+    "sandbox_repo": f"pymc-devs/pymc-sandbox/{version}",
     "doc_path": "doc",
     "default_mode": "light",
 }
 
+# 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_extra_path = ["_thumbnails", 'images', "robots.txt"]
+templates_path = [".templates"]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -295,3 +299,62 @@ def find_source():
 
 # If false, no module index is generated.
 # latex_use_modindex = True
+
+
+# -- MyST config  -------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "amsmath",
+    "substitution",
+]
+myst_dmath_double_inline = True
+
+citation_code = f"""
+```bibtex
+@incollection{{citekey,
+  author    = "<notebook authors, see above>",
+  title     = "<notebook title>",
+  editor    = "Pytensor Team",
+  booktitle = "Pytensor Examples",
+}}
+```
+"""
+
+myst_substitutions = {
+    "pip_dependencies": "{{ extra_dependencies }}",
+    "conda_dependencies": "{{ extra_dependencies }}",
+    "extra_install_notes": "",
+    "citation_code": citation_code,
+}
+
+nb_execution_mode = "off"
+nbsphinx_execute = "never"
+nbsphinx_allow_errors = True
+
+rediraffe_redirects = {
+    "index.md": "gallery.md",
+}
+
+# -- Bibtex config  -------------------------------------------------
+bibtex_bibfiles = ["references.bib"]
+bibtex_default_style = "unsrt"
+bibtex_reference_style = "author_year"
+
+
+# -- ablog config  -------------------------------------------------
+blog_baseurl = "https://pytensor.readthedocs.io/en/latest/index.html"
+blog_title = "Pytensor Examples"
+blog_path = "blog"
+blog_authors = {
+    "contributors": ("Pytensor Contributors", "https://pytensor.readthedocs.io"),
+}
+blog_default_author = "contributors"
+post_show_prev_next = False
+fontawesome_included = True
+# post_redirect_refresh = 1
+# post_auto_image = 1
+# post_auto_excerpt = 2
+
+# notfound_urls_prefix = ""

doc/core_development_guide.rst

@@ -26,12 +26,4 @@ some of them might be outdated though:
 
 * :ref:`unittest` -- Tutorial on how to use unittest in testing PyTensor.
 
-* :ref:`sandbox_debugging_step_mode` -- How to step through the execution of
-  an PyTensor function and print the inputs and outputs of each op.
-
-* :ref:`sandbox_elemwise` -- Description of element wise operations.
-
-* :ref:`sandbox_randnb` -- Description of how PyTensor deals with random
-  numbers.
-
 * :ref:`sparse` -- Description of the ``sparse`` type in PyTensor.

doc/environment.yml

@@ -14,6 +14,14 @@ dependencies:
   - pillow
   - pymc-sphinx-theme
   - sphinx-design
+  - pygments
+  - pydot
+  - ipython
+  - myst-nb
+  - matplotlib
+  - watermark
+  - ablog
   - pip
   - pip:
+    - sphinx_sitemap
     - -e ..

doc/extending/creating_a_numba_jax_op.rst

@@ -1,13 +1,13 @@
 Adding JAX, Numba and Pytorch support for `Op`\s
-=======================================
+================================================
 
 PyTensor is able to convert its graphs into JAX, Numba and Pytorch compiled functions. In order to do
 this, each :class:`Op` in an PyTensor graph must have an equivalent JAX/Numba/Pytorch implementation function.
 
 This tutorial will explain how JAX, Numba and Pytorch implementations are created for an :class:`Op`.
 
 Step 1: Identify the PyTensor :class:`Op` you'd like to implement
-------------------------------------------------------------------------
+-----------------------------------------------------------------
 
 Find the source for the PyTensor :class:`Op` you'd like to be supported and
 identify the function signature and return values. These can be determined by
@@ -98,7 +98,7 @@ how the inputs and outputs are used to compute the outputs for an :class:`Op`
 in Python. This method is effectively what needs to be implemented.
 
 Step 2: Find the relevant method in JAX/Numba/Pytorch (or something close)
----------------------------------------------------------
+--------------------------------------------------------------------------
 
 With a precise idea of what the PyTensor :class:`Op` does we need to figure out how
 to implement it in JAX, Numba or Pytorch. In the best case scenario, there is a similarly named
@@ -269,7 +269,7 @@ and :func:`torch.cumprod`
             z[0] = np.cumprod(x, axis=self.axis)
 
 Step 3: Register the function with the respective dispatcher
----------------------------------------------------------------
+------------------------------------------------------------
 
 With the PyTensor `Op` replicated, we'll need to register the
 function with the backends `Linker`. This is done through the use of

doc/gallery/page_footer.md

@@ -0,0 +1,27 @@
+## License notice
+All the notebooks in this example gallery are provided under a
+[3-Clause BSD License](https://github.com/pymc-devs/pytensor/blob/main/doc/LICENSE.txt)
+which allows modification, and redistribution for any
+use provided the copyright and license notices are preserved.
+
+## Citing Pytensor Examples
+
+To cite this notebook, please use the suggested citation below.
+
+:::{important}
+Many notebooks are adapted from other sources: blogs, books... In such cases you should
+cite the original source as well.
+
+Also remember to cite the relevant libraries used by your code.
+:::
+
+Here is an example citation template in bibtex:
+
+{{ citation_code }}
+
+which once rendered could look like:
+
+<!-- continues in _templates/page.html!!! -->
+<!-- I wanted to get some kind of automation to the process,
+and html templates have access to many variables that are not available
+from jinja-myst -->