Investigating an issue with the embedded link Open with Colab badge on our organisationally-hosted `.ipynb` assets

[anisa-hawes]

I am opening this Issue to set out a puzzling issue relating to the embedded links within the Open with Colab badges on our organisationally-hosted .ipynb assets.

--

Context

In dialogue with the Managing Editors, we have agreed some guiding principles and workflows that enable us to manage codebooks as assets that are sustainable, translatable, and can be used flexibly by our readers.

We are hosting codebooks in our organisational Colab, which is part of our Google Workspace. At Phase 1 Submission, as part of the work done to process new lesson materials, the publishing team are uploading codebooks to Colab and utilising the facility to Save a Copy in GitHub that creates a copy of the file directly in ph-submissions:

• File > Save a Copy in GitHub

• Enter the following into the dialogue box:

• Repository:
  programminghistorian/ph-submissions

• Branch:
  gh-pages

• File path:
  assets/lesson-slug/lesson-slug.ipynb

• Commit message:
  Create lesson-slug.ipynb

• Include a link to Colaboratory:
  [YES]

This Save a Copy action generates an active Open with Colab 'badge' in the upper left corner of the rendered file in ph-submissions. This means reviewers and editors can choose to click and use Colab to test run the code.

Problem

We cannot replicate this workflow in Jekyll, because we want our PR workflow to integrate our build checks and a colleague's review.

In a previous discussion #3001, we agreed a workflow for uploading codebooks to Jekyll which has been operating smoothly until now. This involves us manually uploading our .ipynb asset first (in a PR which precedes the publication) so that we can include a live nbviewer link in the published lesson.

However we've since noticed that when clicking on the Open with Colab badge in a codebook featured in a published lessons, we encounter a link error: /corpus-analysis-with-spacy.ipynb

What is happening is that the link embedded within the badge has automatically fixed to the temporary branch we used to publish the lesson (where we are referencing the codebook as an asset) (see 3053/files#diff):

--

Trying to find a workable alternative

During some recent updates to the codebook associated with /en/lessons/clustering-visualizing-word-embeddings 3182/files we tested again. The only way I could fix the Issue was to bypass our established PR + colleague's review workflow, and use my Repo Owner credentials to make a direct commit to gh-pages when establishing the link with Save a Copy in GitHub: /clustering-visualizing-word-embeddings.ipynb.

This is (clearly) not a preferred practice, so I would like to ask for some help to find workable alternative.

A few notes/thoughts:

• The code element that defines the 'badge' link isn't something we can edit manually within the .ipynb file
• As part of Lesson Maintenance we need to be able to make amendments to codebooks, and be able to maintain two synchronised files (one on Colab, one on Jekyll)
• The facility to save a file from Colab into GitHub means that other people must be doing this...
• and other people must be (as we do) deleting their temporary branches after merging a commit

--

Hello @ZoeLeBlanc and @rivaquiroga,

Do you have any ideas how I could amend this workflow so that the 'badges' are operable after publication?

Thank you for your support to think this through.

A.

[anisa-hawes]

Noting here that I have made three further updates as direct commits:

• I've updated a codeblock in clustering-visualizing-word-embeddings.ipynb towards fixing #3160 : https://github.com/programminghistorian/jekyll/commit/2992636eb1febe66164c2aeb32152566e2f2f7ce
• I've re-saved corpus-analysis-with-spacy.ipynb so that the 'badge' is linked to the file as saved in gh-pages https://github.com/programminghistorian/jekyll/commit/7ff7e4dd59ed1cc49bf95cd92e546e9d28fda59b
• I've saved computer-vision-deep-learning-pt-1-2.ipynb: https://github.com/programminghistorian/jekyll/commit/3f7256327c5c355b8b3d55083cea6859b563c759. We are working on migrating this notebook from Kaggle to Colab so that it aligns with the guidelines we've developed, and so that we can access it for maintenance and ensure the lesson's sustainability into the future.
• I've added the notebook facial-recognition-ai-python.ipynb : https://github.com/programminghistorian/jekyll/commit/dd44d770b574df709417a11f28af89504134ef1a

[anisa-hawes]

Closing this investigation to confirm that when setting up codebooks, the Publishing Team can bypass Colab's Save a Copy in GitHub action and instead upload/create .ipynb files directly, then simply add the following cell to our file which creates the Open in Colab badge (which offers readers the option of opening codebooks in their local Google Drive):

In Jekyll:

{
     "cell_type": "markdown",
     "metadata": {
      "colab_type": "text",
      "id": "view-in-github"
     },
     "source": [
      "<a href=\"https://colab.research.google.com/github/programminghistorian/jekyll/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
     ]
    },

In ph-submissions:

{
     "cell_type": "markdown",
     "metadata": {
      "colab_type": "text",
      "id": "view-in-github"
     },
     "source": [
      "<a href=\"https://colab.research.google.com/github/programminghistorian/ph-submissions/blob/gh-pages/assets/lesson-slug/lesson-slug.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
     ]
    },

With thanks to @charlottejmc for collaborative puzzling + testing! ✨ and thanks also to @eliselavy for insights shared 👐🏼