Examples page

.github/workflows/cookbook_pr_closed.yaml

@@ -0,0 +1,29 @@
+name: Clean up PR cache
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - main
+
+jobs:
+  preprocess:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout deployment branch
+        uses: actions/checkout@v3
+        with:
+          ref: _cookbook_data
+          clean: false
+
+      - name: Clean up PR cache
+        shell: bash -l {0}
+        run: |
+          rm -r PR${{ github.event.number }}
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add .
+          git commit --amend -m "Deploy pre-processed notebook cache"
+          git push --force origin _cookbook_data

.github/workflows/cookbook_pr_opened.yaml

@@ -0,0 +1,55 @@
+name: Generate PR cache by copying main
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+    branches:
+      - main
+
+jobs:
+  preprocess:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout deployment branch
+        uses: actions/checkout@v3
+        with:
+          ref: _cookbook_data
+          clean: false
+
+      - name: Copy cache from main to PR folder and deploy
+        shell: bash -l {0}
+        run: |
+          cp -r main PR${{ github.event.number }}
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add .
+          git commit --amend -m "Deploy pre-processed notebook cache"
+          git push --force origin _cookbook_data
+
+      - name: Add descriptive comment to PR
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: >
+            This repository caches data generated from notebooks stored in other
+            repositories in the `_cookbook_data` branch. Regenerating this cache
+            takes about half an hour, so it is not done automatically in PRs.
+            The current value of the cache from the `main` branch has been
+            copied over to this PR's cache.
+
+
+            To regenerate the cache, navigate to the [`cookbook_preproc`
+            action], click "Run workflow", select the current branch and enter
+            the PR number (`${{ github.event.number }}`), and then click the
+            green "Run workflow" button.
+
+
+            Note that the RTD build must be executed after the
+            `cookbook_preproc` action has finished for its results to be
+            visible, which can be done from the appropriate [build page].
+
+
+            [`cookbook_preproc` action]: https://github.com/openforcefield/openff-docs/actions/workflows/cookbook_preproc.yaml
+            [build page]: https://readthedocs.org/projects/openff-docs/builds/

.github/workflows/cookbook_preproc.yaml

@@ -2,8 +2,14 @@ name: Pre-process example notebooks
 
 on:
   workflow_dispatch:
-  # TODO: Run when source repo releases are available on Conda Forge
-  # TODO: Run when the examples Conda environment is changed
+    inputs:
+      pr_number:
+        description: 'Update the cache for PR#: (leave blank if not a PR)'
+        required: false
+        default: ""
+        type: string
+  schedule:
+    - cron: 0 0 * * * # 1/day at midnight UTC
 
 jobs:
   preprocess:
@@ -24,23 +30,42 @@ jobs:
           path: 'deploy'
           clean: false
 
+      - name: Choose deployment subdirectory
+        shell: bash -l {0}
+        run: |
+          if [[ ${{ github.event_name }} != "workflow_dispatch" ]]; then
+            echo "DEPLOY_SUBDIR=$GITHUB_REF_NAME" >> "$GITHUB_ENV"
+          elif [[ "${{ inputs.pr_number }}" == "" ]]; then
+            echo "DEPLOY_SUBDIR=$GITHUB_REF_NAME" >> "$GITHUB_ENV"
+          else
+            echo "DEPLOY_SUBDIR=PR${{ inputs.pr_number }}" >> "$GITHUB_ENV"
+          fi
+
       - name: Prepare cache deployment directory
         shell: bash -l {0}
         run: |
-          cd deploy
+          mkdir -p deploy/$DEPLOY_SUBDIR
+          cd deploy/$DEPLOY_SUBDIR
           git config user.name github-actions
           git config user.email [email protected]
-          git rm -r .
+          git rm -r --ignore-unmatch .
 
       - name: Pre-process and execute notebooks
         shell: bash -l {0}
         run: |
-          python source/_ext/proc_examples.py --prefix=deploy
+          python source/_ext/proc_examples.py --prefix=deploy/$DEPLOY_SUBDIR --cache-prefix=$DEPLOY_SUBDIR
 
       - name: Deploy cache
         shell: bash -l {0}
         run: |
-          cd deploy
+          cd deploy/$DEPLOY_SUBDIR
           git add .
-          git commit -m "Deploy pre-processed notebook cache"
-          git push origin _cookbook_data
+          git commit --amend -m "Deploy pre-processed notebook cache"
+          git push --force origin _cookbook_data
+
+      - name: Trigger RTD build
+        # RTD doesn't offer a way to manually trigger builds in PRs, so we'll just do this for other builds
+        if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.pr_number == '')
+        shell: bash -l {0}
+        run: |
+          curl -X POST -d "branches=$GITHUB_REF_NAME" -d "token=${{ secrets.RTD_WEBHOOK_TOKEN }}" https://readthedocs.org/api/v2/webhook/openff-docs/243876/

.github/workflows/lint.yaml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Install Conda environment
-        uses: mamba-org/provision-with-micromamba@main
+        uses: mamba-org/setup-micromamba@v1
         with:
           environment-file: devtools/conda-envs/lint_env.yml
 

.gitignore

@@ -2,6 +2,7 @@
 build/
 
 # Cookbook files
+source/examples/
 source/_cookbook/
 
 # Python stuff

.readthedocs.yaml

@@ -6,5 +6,19 @@ build:
   os: ubuntu-20.04
   tools:
     python: "mambaforge-4.10"
+  apt_packages:
+    - rsync
+  jobs:
+    post_install:
+      - git clone -v --depth=1 --single-branch --branch=_cookbook_data -- https://github.com/openforcefield/openff-docs.git build/_cookbook_data
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then
+          # This is a PR, so use the PR number
+          SOURCE_PATH="build/_cookbook_data/PR${READTHEDOCS_VERSION_NAME}"
+        else
+          # This is not a PR, so use the Git reference
+          SOURCE_PATH="build/_cookbook_data/${READTHEDOCS_GIT_IDENTIFIER}"
+        fi
+        rsync -a "${SOURCE_PATH}"/* ./
 conda:
   environment: devtools/conda-envs/rtd_env.yml

devtools/conda-envs/examples_env.yml

@@ -4,19 +4,24 @@ channels:
 dependencies:
     - pip
     - python=3.10
+    - jupyterlab>=4
+    - ipywidgets>=8
     # Cookbook
     - gitpython
     - nbconvert
     - nbformat
     - requests
     - packaging
     # Examples
-    - openff-toolkit-examples
-    - openff-interchange==0.3.5 # Pin Interchange 0.3.5 because 0.3.6 has a broken example
+    - openff-toolkit-examples>=0.14.0
+    - openff-interchange>=0.3.7
     - openff-nagl==0.2.2
+    # - openff-fragmenter
+    # - openff-qcsubmit
     - gromacs >=2021=nompi*
     - lammps
     - rich
     - jax
     - dglteam/label/cu118::dgl
     - parmed<4
+    - nglview>=3.0.6

devtools/conda-envs/lint_env.yml

@@ -6,7 +6,13 @@ dependencies:
     # readthedocs dependencies
     - sphinx>=5,<7
     - myst-parser>=1,<2
+    # - myst-nb
     - sphinx-notfound-page
+    - ipython >=8.8
+    - sphinx-design
+    - gitpython
+    - nbconvert
+    - nbformat
     # Code example deps
     - openff-toolkit-base
     - openff-interchange-base
@@ -18,3 +24,5 @@ dependencies:
         - git+https://github.com/openforcefield/openff-sphinx-theme.git@main
         # Lints
         - sphinxawesome-codelinter
+        # Sphinx
+        - git+https://github.com/Yoshanuikabundi/MyST-NB.git@upgrade-to-1

devtools/conda-envs/rtd_env.yml

@@ -6,10 +6,19 @@ dependencies:
     # readthedocs dependencies
     - sphinx>=5,<7
     - myst-parser>=1,<2
+    # - myst-nb
     - sphinx-notfound-page
+    - ipython >=8.8
+    - sphinx-design
+    # Examples
+    - gitpython
+    - nbconvert
+    - nbformat
     # Theme
     - pip:
         # Theme
         - git+https://github.com/openforcefield/openff-sphinx-theme.git@main
         # Lints
         - sphinxawesome-codelinter
+        # Sphinx
+        - git+https://github.com/Yoshanuikabundi/MyST-NB.git@upgrade-to-1