Add header links to github/colab/binder

Add ablog with tags, authors, and categories

Modify example notebooks

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,21 +1,3 @@
-# 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
@@ -37,6 +19,7 @@
     "sphinx.ext.mathjax",
     "sphinx_design",
     "sphinx.ext.intersphinx",
+    "ablog",
     "myst_nb",
     "generate_gallery",
 ]
@@ -96,6 +79,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.
@@ -160,15 +144,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".
@@ -311,18 +307,50 @@ def find_source():
 ]
 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 = "/projects/examples/en/latest/"

doc/environment.yml

@@ -20,6 +20,7 @@ dependencies:
   - myst-nb
   - matplotlib
   - watermark
+  - ablog
   - pip
   - pip:
     - -e ..

doc/gallery/page_footer.md

@@ -0,0 +1,27 @@
+## License notice
+All the notebooks in this example gallery are provided under the
+[MIT License](https://github.com/pymc-devs/pytensor/blob/main/LICENSE)
+which allows modification, and redistribution for any
+use provided the copyright and license notices are preserved.
+
+## Citing PyMC examples
+
+To cite this notebook, use the DOI provided by Zenodo for the pytensor repository.
+
+:::{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 automatation to the process,
+and html templates have access to many variables that are not available
+from jinja-myst -->