Add Docs for Binder Badge w/GitHub Actions

doc/conf.py

@@ -3,14 +3,8 @@
 
 import os
 import requests
-from recommonmark.transform import AutoStructify
 github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
 def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Contents',
-            }, True)
-    app.add_transform(AutoStructify)
     app.add_stylesheet('custom.css')
 
 
@@ -23,7 +17,7 @@ def setup(app):
 # 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_copybutton']
+extensions = ['sphinx_copybutton', 'myst_parser']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -33,12 +27,6 @@ def setup(app):
 
 source_suffix = ['.rst', '.md']
 
-from recommonmark.parser import CommonMarkParser
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -198,4 +186,4 @@ def setup(app):
             ff.write('.. ##################################################\n')
             ff.write('.. THIS PAGE IS AUTOMATICALLY IMPORTED FROM {}.\n.. DO NOT EDIT IT DIRECTLY.\n'.format(this_url))
             ff.write('.. ##################################################\n\n')
-            ff.write(resp.text)
+            ff.write(resp.text)

doc/doc-requirements.txt

@@ -1,9 +1,9 @@
-recommonmark==0.4.0
+myst_parser
 sphinx_copybutton
 traitlets
 jupyterhub
-sphinx>=1.3.6,!=1.5.4
 memory_profiler
 pytest
 PyGitHub
 pydata_sphinx_theme
+

doc/howto/binder-badge-permissions.yaml

@@ -0,0 +1,28 @@
+#./github/workflows/binder-badge-permissions.yaml
+name: Binder Badge
+on: [pull_request]
+
+jobs:
+  binder:
+    if: |         
+        ((github.event.issue.author_association != 'OWNER') ||
+        (github.event.issue.author_association != 'COLLABORATOR') ||
+        (github.event.issue.author_association != 'CONTRIBUTOR') ||
+        (github.event.issue.author_association != 'MEMBER'))
+
+    runs-on: ubuntu-latest
+    steps: 
+    - name: comment on PR with Binder link
+      uses: actions/github-script@v1
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+          var BRANCH_NAME = process.env.BRANCH_NAME;
+          github.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch`
+          }) 
+      env:
+        BRANCH_NAME: ${{ github.event.pull_request.head.ref }}

doc/howto/binder-badge.yaml

@@ -0,0 +1,22 @@
+#./github/workflows/binder-badge.yaml
+name: Binder Badge
+on: [pull_request]
+
+jobs:
+  binder:
+    runs-on: ubuntu-latest
+    steps: 
+    - name: comment on PR with Binder link
+      uses: actions/github-script@v1
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+          var BRANCH_NAME = process.env.BRANCH_NAME;
+          github.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch`
+          }) 
+      env:
+        BRANCH_NAME: ${{ github.event.pull_request.head.ref }}

doc/howto/chatops-binder.yaml

@@ -0,0 +1,34 @@
+#./github/workflows/chatops-binder.yaml
+name: Chatops Binder
+on: [issue_comment] # issues and PRs are equivalent in terms of comments for the GitHub API
+
+jobs:
+  trigger-chatops:
+    # Make sure the comment is on a PR, and contains the command "/binder"
+    if: (github.event.issue.pull_request != null) &&  contains(github.event.comment.body, '/binder')
+    runs-on: ubuntu-latest
+    steps:
+      # Use the GitHub API to: 
+      #  (1) Get the branch name of the PR that has been commented on with "/binder" 
+      #  (2) make a comment on the PR with the binder badge
+    - name: comment on PR with Binder link
+      uses: actions/github-script@v1
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+         // Get the branch name
+         octokit.pulls.get({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            pull_number: context.payload.issue.number
+         }).then( (pr) => {
+
+            // use the branch name to make a comment  on the PR with a Binder badge
+            var BRANCH_NAME = pr.data.head.ref
+            octokit.issues.createComment({
+               issue_number: context.payload.issue.number,
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch`
+               })
+         })

doc/howto/gh-actions-badges.md

@@ -0,0 +1,61 @@
+# Use GitHub Actions To Place A MyBinder.org Badge On Pull Requests
+
+You can facilitate review of GitHub pull requests on [mybinder.org](https://mybinder.org) by using [GitHub Actions](https://github.com/features/actions) to place a ![Binder](https://mybinder.org/badge_logo.svg) badge or link on Pull Requests.  Below are several examples of how to accomplish this.
+
+To enable GitHub Actions, you must place .yaml files that define your GitHub Action workflow in the `/.github/workflows/` directory in your repository.
+
+
+## Example 1: Comment on pull request with a binder badge
+
+```{note}
+This example will not work on pull requests from forks.  This is to protect repositories from malicious actors.  To trigger a GitHub Action with sufficient permissions to comment on a pull request from a fork, you must trigger the action via another event, such as a comment or a label.  This is demonstrated in Example 2 below._
+```
+
+The below action uses the [github/script](https://github.com/actions/github-script) Action to call the [GitHub API](https://docs.github.com/en/rest/reference/issues#comments) for the purposes of making a comment on a PR that looks like this:
+
+> ![Binder](https://mybinder.org/badge_logo.svg) 👈 Launch a binder notebook on this branch
+
+Download the below file: {download}`binder-badge.yaml <./binder-badge.yaml>`
+
+```{literalinclude} ./binder-badge.yaml
+---
+language: yaml
+---
+```
+
+## Example 2: Comment with a Binder badge in response to a comment
+
+In the below example, we will trigger GitHub Actions to run after someone comments on a pull request with the command `/binder`, which will trigger Actions to comment on a PR in the same way as Example 1.
+
+Download the below file: {download}`chatops-binder.yaml <./chatops-binder.yaml>`
+
+```{literalinclude} ./chatops-binder.yaml
+---
+language: yaml
+---
+```
+
+## Permissions
+
+You may want to restrict who can trigger a binder badge to be created by [their association](https://developer.github.com/v4/enum/commentauthorassociation/) with a repository.  When triggering GitHub Actions on an [issue_comment](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#issue_comment) event, you can 
+access the association of the person who opened the pull request with the variable `github.event.issue.author_association` and the person commenting on the pull request with `github.event.comment.author_association`. 
+
+```{note}
+An `issue_comment` event is triggered when you comment on a pull request.  This is because the GitHub API treats issues and pull requests as the same entity in many places.  This is also why you can access the association of the person who opened the pull request with the `github.event.issue.author_association` when the `issue_comment` event occurs.
+```
+
+Similarly, when triggering GitHub Actions on a [pull_request](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request) event, you can access the association of the person who opened the pull request with the variable `github.event.pull_request.author_association`.
+
+For example, this is how you can conditionally trigger the workflow shown in **Example 1** if the person opening the PR is a `OWNER`, `COLLABORATOR`, `CONTRIBUTOR`, or `MEMBER`:
+
+Download the below file: {download}`binder-badge-permissions.yaml <./binder-badge-permissions.yaml>`
+
+```{literalinclude} ./binder-badge-permissions.yaml
+---
+language: yaml
+---
+```
+
+## Further Reading
+
+There are many more ways you can customize your workflows to suit your needs.  Please see the official GitHub Actions [documentation](https://docs.github.com/en/actions) for more information.

doc/howto/index.rst

@@ -15,3 +15,4 @@ accomplish something specific.
    badges
    repo_data
    lab_workspaces
+   gh-actions-badges