Add tutorials section to cookbook (#16)

* Add tutorials

 * split cookbook and tutorials into two different pages
 * add new basic introductionary tutorial
 * add the old OpenMM 7 tutorials as is from existing docs

* Update gh-pages.yml

set follow_symlinks to true otherwise the "latest" symlink in gh-pages branch causes issues with build process

* split cookbook and tutorial pages

* clean up alchemical free energy tutorial

* cleanup and update readme

* get back default thumbnails

.github/workflows/gh-pages.yml

@@ -100,6 +100,7 @@ jobs:
           jekyll: false
           commit_message: "Deploy to GH Pages"
           keep_history: true
+          follow_symlinks: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -122,4 +123,4 @@ jobs:
           issue-number: ${{ github.event.pull_request.number }}
           body: |
             Example docs for this PR [rendered here](https://openmm.github.io/openmm-cookbook/PR${{ github.event.number }})
-          edit-mode: replace
+          edit-mode: replace

README.md

@@ -1,20 +1,46 @@
 # openmm-cookbook
-Proof-of-concept for the OpenMM Cookbook.
+
+This repo is home to the OpenMM Cookbook and the OpenMM Tutorials
 
 Preview at https://openmm.github.io/openmm-cookbook
 
 ## Adding a notebook
 
-A notebooks can be added to the cookbook by adding it to a subfolder of the `notebooks` folder. Links to download the notebook, view it in GitHub, or open it in Google Colab are added to the rendered notebook on the website automatically. Any files required by the notebook should be placed in the same folder as the notebook --- they are required by both the testing apparatus and Google Colab. The notebook must also be added to `index.md`.
+To add a new cookbook add the ipynb notebook to the `notebooks/cookbook` folder and add a link to it in `cookbook.md`. To add a new tutorial add the ipynb notebook to the `notebooks/tutorials` folder and add a link to it in `tutorials.md`
+
+Links to download the notebook, view it in GitHub, or open it in Google Colab are added to the rendered notebook on the website automatically. Any files required by the notebook should be placed in the same folder as the notebook --- they are required by both the testing apparatus and Google Colab. The notebook must also be added to `index.md`.
 
 "Open in Google Colab" links to a copy of the notebook that is constructed when the documentation is built. This copy has a cell injected that allows the notebook's dependencies to be installed automatically. By default, each notebook will install the Conda Forge packages specified in the `cookbook_default_conda_forge_deps` variable in `conf.py`, and then download all the files in the notebook's folder into the notebook's execution environment. This can be configured on a per-notebook basis by adding the `conda_forge_dependencies` or `required_files` metadata entries to the notebook.
 
-Notebook thumbnails can be configured in several ways, as described in the [nbsphinx documentation].
+Notebook thumbnails can be configured in several ways, as described in the [nbsphinx documentation](https://nbsphinx.readthedocs.io/).
+
+
+## Building locally
+
+First clone this repo, then create a conda environment using [environment.yml](environment.yml).
+The cookbook can then be built using
+```
+make html
+```
+the created html will be in the `build/html` directory and can be viewed by opening `build/html/index.html` in a browser.
 
 ## Releases
 
-The cookbook's `main` branch is intended for use with the latest release of OpenMM. When new cookbooks are added, they will be served immediately and tested against the current release. Nightly tests are performed against OpenMM's development branch, and any fixes required will live in feature branches or a `next` branch. When a new release of OpenMM is cut, the state of `main`, which reflects an entire release cycle, is memorialized with a release tag and rendered to gh-pages in its own release folder. Any feature branches or `next` branches are then merged in so that `main` is now compatible with the new release.
+The cookbooks main branch is the development channel, it is rendered as `https://openmm.github.io/openmm-cookbook/dev/`, anytime the main branch is updated the rendered cookbook will be updated.
+
+When a release is cut the current working state of the cookbook will be preserved as `https://openmm.github.io/openmm-cookbook/refs/tags/${release}/index.html` where `${release}` is the release tag. e.g. `https://openmm.github.io/openmm-cookbook/refs/tags/v0.1/index.html`.
+
+
+ The latest version of the cookbook will point to the most recent release `https://openmm.github.io/openmm-cookbook/latest/`
+
+## CI
+
+Continuous integration is run on the main branch of the cookbook. Just the notebooks in `notebooks/cookbook` are run through the CI, tutorials are not (due to long compute time). There are two workflows: [Main](.github/workflows/ci-main.yml) will test that the notebooks run with the latest release of OpenMM, [Nightly](.github/workflows/ci-nightly.yml) will test that the notebooks run with the development version of OpenMM.
+
+## Pull Requests
+
+When a PR is triggered the cookbook will be rendered as `https://openmm.github.io/openmm-cookbook/PR#/` where PR# is the pull request number e.g. [PR16](https://openmm.github.io/openmm-cookbook/PR16/index.html). **Note** that due to github actions permissions the *Deploy to GitHub Pages* step in the [gh-pages workflow](.github/workflows/gh-pages.yml) will only work correctly if the PR comes from a branch *within* `https://github.com/openmm/openmm-cookbook` and it will not work when the PR comes from a personal fork.
+
+
 
-This strategy allows cookbooks for the current version to be released instantly while still permitting testing of notebooks in CI, and preserving the state of the cookbook at each release for posterity.
 
-[nbsphinx documentation]: https://nbsphinx.readthedocs.io/en/0.8.7/subdir/gallery.html

conf.py

@@ -17,8 +17,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "OpenMM Cookbook"
-copyright = "2022, The OpenMM Contributors"
+project = "OpenMM Cookbook & Tutorials"
+copyright = "2023, The OpenMM Contributors"
 author = "The OpenMM Contributors"
 release = os.getenv("PAGES_DEPLOY_PATH","dev")
 print(release)

cookbook.md

@@ -0,0 +1,60 @@
+---
+orphan: true
+---
+# The OpenMM Cookbook
+
+
+## Getting Started
+
+:::{nbgallery}
+---
+glob: True
+caption: Getting Started
+---
+notebooks/cookbook/first_simulation.ipynb
+
+:::
+
+## Simulation Protocols
+
+:::{nbgallery}
+---
+glob: True
+caption: Simulation Protocols
+---
+notebooks/cookbook/Changing Temperature and Pressure
+notebooks/cookbook/Saving Systems to XML Files
+notebooks/cookbook/Merging Molecules
+notebooks/cookbook/Adding Hydrogens to Nonstandard Molecules
+:::
+
+## Restraints, Constraints, and External Forces
+
+:::{nbgallery}
+---
+glob: True
+caption: Restraints, Constraints, and External Forces
+---
+notebooks/cookbook/Applying a Constant External Force
+notebooks/cookbook/Constraining Atom Positions
+notebooks/cookbook/Restraining Atom Positions
+notebooks/cookbook/Restraining Dihedrals
+:::
+
+## Analysis and System Inspection
+
+:::{nbgallery}
+---
+glob: True
+caption: Analysis and System Inspection
+---
+notebooks/cookbook/Analyzing Energy Contributions
+notebooks/cookbook/Querying Charges and Other Parameters
+:::
+
+
+----
+
+[Notebooks by Tag](genindex)
+
+

environment.yml

@@ -5,7 +5,7 @@ dependencies:
   - python >= 3.7
   - pip
   - sphinx>=4.0.0,<5
-  - nbsphinx
+  - nbsphinx<0.9.0 #keep default thumbnails from sphinx_gallery.load_style https://github.com/spatialaudio/nbsphinx/releases/tag/0.9.0
   - nbformat<5.2 #https://github.com/jupyter/nbformat/issues/303
   - pytest
   - nbval

index.md

@@ -1,65 +1,20 @@
 # The OpenMM Cookbook
+[Click here for the OpenMM Cookbook](cookbook.md)
 
-## Getting Started
+The OpenMM Cookbook contains short code examples for common tasks you can perform in OpenMM. 
+The examples can be run directly in Colab, the runtime is a few seconds for each one.
 
-:::{nbgallery}
----
-glob: True
-caption: Getting Started
----
-notebooks/cookbook/first_simulation.ipynb
-
-:::
-
-## Simulation Protocols
-
-:::{nbgallery}
----
-glob: True
-caption: Simulation Protocols
----
-notebooks/cookbook/Changing Temperature and Pressure
-notebooks/cookbook/Saving Systems to XML Files
-notebooks/cookbook/Merging Molecules
-notebooks/cookbook/Adding Hydrogens to Nonstandard Molecules
-:::
-
-## Restraints, Constraints, and External Forces
-
-:::{nbgallery}
----
-glob: True
-caption: Restraints, Constraints, and External Forces
----
-notebooks/cookbook/Applying a Constant External Force
-notebooks/cookbook/Constraining Atom Positions
-notebooks/cookbook/Restraining Atom Positions
-notebooks/cookbook/Restraining Dihedrals
-:::
-
-## Analysis and System Inspection
-
-:::{nbgallery}
----
-glob: True
-caption: Analysis and System Inspection
----
-notebooks/cookbook/Analyzing Energy Contributions
-notebooks/cookbook/Querying Charges and Other Parameters
-:::
+# The OpenMM Tutorials
+[Click here for the OpenMM Tutorials](tutorials.md)
 
-## Tutorials
+The OpenMM Tutorials are longer examples that walk you through specific simulation methods.
+These can also be run in Colab, but due to the longer compute time required (tens of minutes to hours) you may find it better to run them on your own machine.
 
-:::{nbgallery}
+:::{toctree}
 ---
-glob: True
-caption: Tutorials
+hidden: true
+maxdepth: 3
 ---
-:::
-
-
-----
-
-[Notebooks by Tag](genindex)
-
-
+cookbook.md
+tutorials.md
+:::

notebooks/cookbook/first_simulation.ipynb

@@ -64,7 +64,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.9.13 ('openmm')",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -78,7 +78,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.6 (default, Sep 26 2022, 11:37:49) \n[Clang 14.0.0 (clang-1400.0.29.202)]"
   },
   "tags": [
    "barostat",
@@ -87,7 +87,7 @@
   ],
   "vscode": {
    "interpreter": {
-    "hash": "16b2d2c1789d035bceb6d775bd7ffc39b805c8f0529038638d98b11c7a85ade5"
+    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
    }
   }
  },