Add Documentation

[sef43]

This PR is a try at adding documentation which adresses #2 and comments in #60 .
The format is up for discussion.

I have used a more modern sphinx template than the OpenMM docs: https://pydata-sphinx-theme.readthedocs.io/en/stable/
One key reason for using this template is that it has version switching and warnings available.

The Docs are built by running make html in the doc folder.

Currently there is a userguide section which is just the readme and an API section.

I have included a gh-actions workflow (copied from the cookbook) that renders the docs on the gh-pages branch. The latest commit to main is rendered at /dev. When a release is cut a corresponding version of the docs is created at /<version>. /latest points to the most recent release.

The rendered version for this fork can be seen here: https://sef43.github.io/openmm-ml/dev/index.html (currently just has dev build)

I have made a rest repo with some dummy releases to show the version switching capabilities: https://sef43.github.io/openmm-ml-docs-test/1.1/

[peastman]

This looks like a good start. Embedding the README obviously isn't the right solution long term, but it makes sense as a placeholder until we write a proper manual.

Can you describe a bit about the mechanism for building the docs? Does this mean that every time we merge a pull request, it will automatically commit a new build of the docs to the repository, even if the PR didn't change anything related to docs?

[sef43]

Can you describe a bit about the mechanism for building the docs? Does this mean that every time we merge a pull request, it will automatically commit a new build of the docs to the repository, even if the PR didn't change anything related to docs?

The docs are build using sphinx-build. The commands to do this are provided in a standard sphinx makefile.

Steps to build the docs:

1. create a conda env with doc/environment.yml
2. run the below commands

cd doc
make html

The html docs will now be in doc/build/html.

when a new commit is pushed to main on the repo (or pull request merged) the workflow will build the docs using the above procedure. It then checkouts the gh-pages branch, commits any changes to the html docs, and pushes them back to the gh-pages branch. This all happens in gh-pages:/dev which will be kept up to date with the current state of main. If there are no changes to the generated html then there will be nothing to commit.

If a release is made then the workflow will make a copy of the docs at gh-pages:/refs/tags/<release tag> and gh-pages:/latest will point to the latest released version.

[RaulPPelaez]

I suggest hosting this in https://readthedocs.org

• The readthedocs theme is common and more familiar to readers. Although they do not impose a particular theme.
• You get a clean url like openmm-ml.readthedocs.orgs
• readthedocs hooks with the github project and automcatically builds and post new versions of the documentation at new releases and/or PR mergings.
• You get a per-tag documentation automatically. https://docs.readthedocs.io/en/stable/versions.html

[sef43]

I suggest hosting this in https://readthedocs.org

• The readthedocs theme is common and more familiar to readers. Although they do not impose a particular theme.
• You get a clean url like openmm-ml.readthedocs.orgs
• readthedocs hooks with the github project and automcatically builds and post new versions of the documentation at new releases and/or PR mergings.
• You get a per-tag documentation automatically. https://docs.readthedocs.io/en/stable/versions.html

Open to using read the docs. Not used it before but will have an experiment on a personal test copy! Two points about using readthedocs:

• there will be ads unless we pay. Do we care?
• it will need an account setup for OpenMM with an email/password, who should do this? @peastman @jchodera

I don't think readthedocs adds any functionality we can't get ourselves using gh-pages but definitely looks cleaner and less error prone than the equivalent gh-actions workflows.

[RaulPPelaez]

Just wanted to present it to you as an option :).
In practical purposes adding readthedocs amounts to adding this to this PR as .readthedocs.yaml:

version: "2"

build:
  os: "ubuntu-22.04"
  tools:
     python: "mambaforge-22.9"

conda:
  environment: environment.yml

sphinx:
  configuration: doc/conf.py

And then telling readthedocs.org to take this repo into account.
OTOH the ads point to other projects and are IMO really unintrusive:

[peastman]

I have an allergy to ads of all sorts.

[sef43]

I did try out readthedocs, it definitely works rather easily. Although I think my preference would be hosting the docs ourselves to have more control. We can easily do this using the gh-pages branch on this repo. It can be all automated with gh-actions workflow that we already have from the cookbook (once I clean it up a bit more). We can then always move the docs somewhere else easily (just copy the static pages). And it keeps everything in one place.

[peastman]

I'm fine with keeping the built docs here. Any further comments, or is this ok to merge?

[sef43]

• We will need to create and initialize the gh-pages branch on this repo with a .nojekyll file and a index.html file the same as here first: https://github.com/sef43/openmm-ml/tree/gh-pages

• I need to check and change any urls in this PR that have sef43.github instead of openmm.github

[RaulPPelaez]

As far as I understand there is no way to test this PR unmerged. It requires having a branch with the special name gh-pages in openmm-ml.

[RaulPPelaez]

I am going to merge it in and will reopen to solve any lingering issues.

[RaulPPelaez]

The documentation has been successfully deployed to https://openmm.github.io/openmm-ml/

[peastman]

Thanks! I notice that when I click that link it redirects to https://openmm.github.io/openmm-ml/dev/index.html. Is that the right address?

[RaulPPelaez]

As far as I understand the workflow has two triggers:

• Commits to master -> builds "dev"
• New releases -> builds version_number and sets it to "latest"
  

  openmm-ml/.github/workflows/docs_website.yml

  Lines 66 to 73 in 305597f

  	- name: Prepare release deployment
  	if: success() && github.event_name == 'release'
  	run: |
  	rm -rf deploy/${{ github.ref_name }}
  	mkdir -p deploy/${{ github.ref_name }}
  	mv -T doc/build/html deploy/${{ github.ref_name }}
  	rm -rf deploy/latest
  	ln -s ${{ github.ref_name }} deploy/latest

  
  I could try and commit to gh_pages, copying the current "dev" as 1.1, but I would rather we wait until the docs are as polished as we would like and then do some mock release, like 1.1.1.

[sef43]

Yes exactly that is the intention. It mirrors the openmm docs naming convention. Here is an example of me testing the deployment on a fork with a dummy release: https://sef43.github.io/openmm-ml-docs-test/latest/index.html

[peastman]

Ok, just making sure.