Skip to content

Commit

Permalink
Add example gallery to docs (#1150)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
jessegrabowski authored Jan 13, 2025
1 parent 1fc678c commit 2b57f74
Show file tree
Hide file tree
Showing 26 changed files with 2,334 additions and 90 deletions.
24 changes: 24 additions & 0 deletions doc/.templates/nb-badges.html
Original file line number Diff line number Diff line change
@@ -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 %}
13 changes: 13 additions & 0 deletions doc/.templates/rendered_citation.html
Original file line number Diff line number Diff line change
@@ -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 %}
7 changes: 7 additions & 0 deletions doc/blog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
orphan: true
---

# Recent updates

<!-- auto generated by ablog so it's empty -->
131 changes: 97 additions & 34 deletions doc/conf.py
Original file line number Diff line number Diff line change
@@ -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",
Expand All @@ -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),
Expand Down Expand Up @@ -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.
Expand All @@ -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": [
Expand Down Expand Up @@ -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".
Expand Down Expand Up @@ -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 = ""
8 changes: 0 additions & 8 deletions doc/core_development_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 8 additions & 0 deletions doc/environment.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ dependencies:
- pillow
- pymc-sphinx-theme
- sphinx-design
- pygments
- pydot
- ipython
- myst-nb
- matplotlib
- watermark
- ablog
- pip
- pip:
- sphinx_sitemap
- -e ..
8 changes: 4 additions & 4 deletions doc/extending/creating_a_numba_jax_op.rst
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
27 changes: 27 additions & 0 deletions doc/gallery/page_footer.md
Original file line number Diff line number Diff line change
@@ -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 -->
Loading

0 comments on commit 2b57f74

Please sign in to comment.