Add Documentation

.github/workflows/docs_website.yml

@@ -0,0 +1,87 @@
+name: Documentation website
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  release:
+    types: [published]
+
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Cache conda
+        uses: actions/cache@v2
+        with:
+          path: ~/conda_pkgs_dir
+          key: ${{ runner.os }}-conda-${{hashFiles('environment.yml') }}
+
+      - uses: conda-incubator/setup-miniconda@v2
+        name: Install dependencies
+        with:
+          environment-file: doc/environment.yml
+          auto-activate-base: false
+          miniforge-version: latest
+          miniforge-variant: Mambaforge
+          use-mamba: true
+
+      - name: Describe environment
+        run: |
+          pwd
+          ls
+          conda list
+
+      - name: Install openmm-ml
+        run: |
+          pip install .
+
+      - name: Build Sphinx documentation
+        run: |
+          cd doc
+          make html
+
+      - name: Checkout gh-pages
+        if: success()
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+          path: 'deploy'
+          clean: false
+
+      - name: Prepare development deployment
+        if: success() && github.event_name == 'push'
+        run: |
+          rm -rf deploy/dev
+          mv doc/build/html deploy/dev
+
+      - 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
+
+      - name: Deploy to GitHub Pages
+        if: success()
+        uses: crazy-max/ghaction-github-pages@v2
+        with:
+          target_branch: gh-pages
+          build_dir: deploy
+          jekyll: false
+          commit_message: "Deploy to GH Pages"
+          keep_history: true
+          follow_symlinks: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# sphinx
+generated/

doc/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	python render.py
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)x
+	rm api.rst
+	rm -rf generated

doc/_static/versions.json

@@ -0,0 +1,6 @@
+[
+    {
+        "version": "dev",
+        "url": "https://openmm.github.io/openmm-ml/dev/"
+    }
+]

doc/api.rst.jinja2

@@ -0,0 +1,29 @@
+API
+---
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    openmmml.MLPotential
+
+
+Developer API
+~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    openmmml.mlpotential.MLPotentialImplFactory
+    openmmml.mlpotential.MLPotentialImpl
+
+
+Models
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    {% for model in models %}
+      {{ model }}
+    {% endfor %}

doc/conf.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import openmmml
+import pkg_resources
+import git
+
+
+sys.path.append(os.path.abspath("../"))
+
+
+# version specified in ../setup.py
+version = pkg_resources.require("openmmml")[0].version
+
+repo = git.Repo(search_parent_directories=True)
+short_sha = hash = repo.git.rev_parse(repo.head, short=True)
+
+# get the the current tag if this commit has one
+tag = next((tag for tag in repo.tags if tag.commit == repo.head.commit), None)
+
+if tag is None:
+    release = version + "dev_" + short_sha
+    version_match = "dev"
+    version = version_match
+else:
+    release = str(tag) + "_" + short_sha
+    version_match = str(tag)
+    version = version_match
+
+print("version:", version)
+print("git tag:", tag)
+print("git sha:", short_sha)
+print("release:", release)
+print("version_match", version_match)
+
+
+extensions = [
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "m2r2",
+]
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "member-order": "bysource",
+}
+
+source_suffix = ".rst"
+master_doc = "index"
+
+project = "OpenMM ML"
+copyright = "2023, Stanford University and the Authors"
+
+
+exclude_patterns = ["_build", "_templates"]
+html_static_path = ["_static"]
+templates_path = ["_templates"]
+
+pygments_style = "sphinx"
+
+html_theme = "pydata_sphinx_theme"
+
+html_theme_options = {
+    "logo": {
+        "text": "OpenMM-ML docs",
+        "image_light": "_static/logo.png",
+        "image_dark": "_static/logo.png",
+    },
+    "external_links": [
+        {"name": "OpenMM.org", "url": "https://openmm.org/"},
+        {"name": "OpenMM docs", "url": "https://openmm.org/documentation"},
+        {"name": "GitHub", "url": "https://github.com/openmm"},
+    ],
+    "github_url": "https://github.com/openmm/openmm-ml",
+}
+
+
+# settings for version switcher and warning
+html_theme_options["navbar_start"] = ["navbar-logo", "version-switcher"]
+html_theme_options["switcher"] = {
+    "json_url": "https://openmm.github.io/openmm-ml/dev/_static/versions.json",
+    "version_match": version_match,
+}
+
+# https://github.com/pydata/pydata-sphinx-theme/issues/1552
+html_theme_options["show_version_warning_banner"] = False
+html_theme_options["check_switcher"] = False
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True

doc/environment.yml

@@ -0,0 +1,15 @@
+name: openmm-cookbook
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - pip
+  - sphinx
+  - openmm
+  - pydata-sphinx-theme
+  - pip:
+    - m2r2
+    - GitPython
+
+
+

doc/index.rst

@@ -0,0 +1,10 @@
+.. currentmodule:: openmmml
+
+OpenMM-ML
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   userguide
+   api

doc/render.py

@@ -0,0 +1,54 @@
+"""
+The function of this script is to render the Jinja2 templates in the current
+directory into input files for sphinx. It introspects the OpenMM-ML Python module
+to find all of the classes and formats them for inclusion into the templates.
+"""
+from os.path import dirname, join, splitext, basename
+from glob import glob
+import inspect
+
+import jinja2
+import openmmml
+
+
+
+def fullname(klass):
+    return klass.__module__ + '.' + klass.__name__
+
+
+def models_template_variables():
+    """Create the data structure available to the Jinja2 renderer when
+    filling in the templates.
+
+    This function extracts all of classes in ``openmmml.models`` and returns
+    a list of them
+    """
+    data = {
+        'models': [],
+    }
+
+    for _, module in inspect.getmembers(openmmml.models, predicate=inspect.ismodule):
+        for name, obj in inspect.getmembers(module, predicate=inspect.isclass):
+            if issubclass(obj, openmmml.mlpotential.MLPotentialImpl) and obj != openmmml.mlpotential.MLPotentialImpl:
+                data['models'].append(fullname(obj))
+
+    return data
+
+
+def main():
+    here = dirname(__file__)
+    templateLoader = jinja2.FileSystemLoader(here)
+    templateEnv = jinja2.Environment(loader=templateLoader)
+    data = models_template_variables()
+
+    for template_fn in map(basename, glob(join(here, '*.jinja2'))):
+        output_fn = splitext(template_fn)[0]
+        print('Rendering %s to %s...' % (template_fn, output_fn))
+        template = templateEnv.get_template(template_fn)
+        output_text = template.render(data)
+        with open(output_fn, 'w') as f:
+            f.write(output_text)
+
+
+if __name__ == '__main__':
+    main()

doc/userguide.rst

@@ -0,0 +1,4 @@
+User Guide
+----------
+
+.. mdinclude:: ../README.md