Link to Google Colab button in Notebooks

[hollandjg]

I wanted to highlight a feature of the documentation – the "Open in Google Colab" button.

The code builds on mkdocs-jupyter:

autora/mkdocs.yml

Line 115 in e20b651

mkdocs-jupyter: # required to convert Jupyter notebooks

It is configured using the following lines (as of autora 3.1.0):

autora/mkdocs.yml

Lines 8 to 9 in e20b651

	extra:
	colab_base_url: 'https://colab.research.google.com/github/AutoResearch/autora/blob/gh-pages/'

This block specifies where the notebook can be found.

Note that we're using the "gh-pages" branch version of the notebook – this is the same branch where the documentation itself is stored, so it's guaranteed to be the same as the notebook version which the person is viewing in the docs.

The feature needs two "hooks" which convert strings, loaded here:

autora/mkdocs.yml

Lines 136 to 137 in e20b651

	hooks:
	- mkdocs/hooks.py

... and implemented here:

autora/mkdocs/hooks.py

Lines 5 to 12 in e20b651

	def basename(path):
	return os.path.basename(path)
	def on_env(env, config, files, **kwargs):
	env.filters["basename"] = basename
	env.filters["quote"] = quote
	return env

The actual link and its appearance are specified here:

autora/mkdocs/overrides/main.html

Lines 9 to 12 in e20b651

	<a href="{{ config.extra.colab_base_url }}{{ page.url }}{{ page.file.src_uri | basename | quote }}"
	title="Open Notebook in Google Colab" class="md-content__button md-icon">
	<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
	</a>

This block of HTML uses the two hooks in the snippet

{{ page.file.src_uri | basename | quote }}

• start with the src_uri of the file which generated the page
• basename: get the notebook's filename
• quote: convert any special characters (like spaces) into allowable values for a URL.

The button shown is specified here:

autora/mkdocs/overrides/main.html

Line 11 in e20b651

<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>

The "Download notebook" button is very similar, but doesn't need to use a special starting URL – it can use the "canonical_url":

autora/mkdocs/overrides/main.html

Lines 5 to 8 in e20b651

	<a href="{{ page.canonical_url }}{{ page.file.src_uri | basename | quote }}" title="Download Notebook"
	class="md-content__button md-icon">
	{% include ".icons/material/download.svg" %}
	</a>

Note that this requires the site_url to be set properly:

autora/mkdocs.yml

Line 5 in e20b651

site_url: 'https://autoresearch.github.io/autora/'

(Note here: we noticed that we could have made the code for the Colab link a little simpler if we'd have left the /autora part off the end of the site_url, and we were tempted to do that. However, that misuse of the site_url configuration parameter could have caused more problems down the line – then the canonical_url would have been set wrong in the rest of the site, and any plugins which rely on it would also have broken.)

Potential for development

• Turn it into a plugin for mkdocs which extends mkdocs-jupyter (or add it as a PR to mkdocs-jupyter)
• Add a cleaner hook which does the full conversion, rather than chaining multiple hooks in the html file, perhaps using f"strings".
• Allow for multiple links, like to binder.
• Allow configurable buttons.

[chadcwilliams]

Closing as this is now implemented, well done!