Add Documentation

.github/workflows/website.yml

@@ -0,0 +1,127 @@
+name: website
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  # pull_request:
+  #   branches:
+  #     - main
+  #   types: [opened, edited, synchronize, reopened]
+  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: set dev path
+        run: |
+          echo "PAGES_DEPLOY_PATH=dev" >> $GITHUB_ENV
+        if: github.event_name == 'push'
+      # - name: set PR path
+      #   run: |
+      #     echo "PAGES_DEPLOY_PATH=PR${{ github.event.number }}" >> $GITHUB_ENV
+      #   if: github.event_name == 'pull_request'
+      - name: set release path
+        run: |
+         echo "PAGES_DEPLOY_PATH=${GITHUB_REF}" >> $GITHUB_ENV
+        if: github.event_name == 'release'
+      - 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'
+        env:
+          PR: ${{ github.event.number }}
+        run: |
+          rm -rf deploy/dev
+          mv doc/build/html deploy/dev
+      # - name: Prepare PR deployment
+      #   if: success() && github.event_name == 'pull_request'
+      #   env:
+      #     PR: ${{ github.event.number }}
+      #   run: |
+      #     rm -rf deploy/PR${PR}
+      #     mv build/html deploy/PR${PR}
+      - name: Prepare release deployment
+        if: success() && github.event_name == 'release'
+        env:
+          PR: ${{ github.event.number }}
+        run: |
+          rm -rf deploy/${GITHUB_REF}
+          mkdir -p deploy/${GITHUB_REF}
+          mv -T doc/build/html deploy/${GITHUB_REF}
+          rm -rf deploy/latest
+          ln -s ${GITHUB_REF} 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 }}
+
+      # - name: Find Comment
+      #   if: success() && github.event_name == 'pull_request'
+      #   uses: peter-evans/find-comment@v1
+      #   id: fc
+      #   with:
+      #     issue-number: ${{ github.event.pull_request.number }}
+      #     comment-author: 'github-actions[bot]'
+      #     body-includes: Example docs for this PR
+
+      # - name: Create or update comment
+      #   if: success() && github.event_name == 'pull_request'
+      #   uses: peter-evans/create-or-update-comment@v1
+      #   env:
+      #     PR: ${{ github.event.number }}
+      #   with:
+      #     comment-id: ${{ steps.fc.outputs.comment-id }}
+      #     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

doc/Makefile

@@ -0,0 +1,20 @@
+# 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
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/api.rst

@@ -0,0 +1,24 @@
+API
+---
+
+.. autosummary::
+    :toctree: generated/
+
+    openmmml.MLPotential
+
+
+Models
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    openmmml.models.anipotential.ANIPotentialImpl
+
+
+Developer API
+~~~~~~~~~~~~~
+.. autosummary::
+    :toctree: generated/
+
+    openmmml.mlpotential.MLPotentialImplFactory
+    openmmml.mlpotential.MLPotentialImpl

doc/conf.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+
+sys.path.append(os.path.abspath('../'))
+
+release = os.getenv("PAGES_DEPLOY_PATH","dev").lstrip("refs/tags/")
+
+print(release)
+
+extensions = [
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    # "process-docstring",
+    'm2r2'
+]
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "member-order": "bysource",
+}
+
+source_suffix = ".rst"
+master_doc = "index"
+
+project = u"OpenMM ML Docs"
+copyright = u"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",
+
+    "switcher": {
+        "json_url": "https://sef43.github.io/openmm-ml/versions.json",
+        "version_match": release,
+    },
+
+    "check_switcher": False,
+
+    "navbar_start": ["navbar-logo", "version-switcher"],
+
+    "show_version_warning_banner": True,
+}
+# html_theme_options = {
+#     "github_button": False,
+#     "github_user": "openmm",
+#     "github_repo": "openmm",
+#     "logo_name": True,
+#     "logo": "logo.png",
+#     "extra_nav_links": [
+#         {
+#             "title": "OpenMM.org",
+#             "uri": "https://openmm.org",
+#             "relative": False,
+#         },
+#         {
+#             "title": "User's Manual",
+#             "uri": "../userguide/",
+#             "relative": True,
+#         },
+#         {
+#             "title": "Developer Guide",
+#             "uri": "../developerguide/",
+#             "relative": True,
+#         },
+#         {
+#             "title": "C++ API reference",
+#             "uri": "../api-c++/",
+#             "relative": True,
+#         },
+#         {
+#             "title": "GitHub",
+#             "uri": "https://github.com/openmm",
+#             "relative": False,
+#         },
+#     ],
+#     "show_relbar_bottom": True,
+# }
+# html_sidebars = {
+#     "**": [
+#         "about.html",
+#         "searchbox.html",
+#         "navigation.html",
+#     ]
+# }
+
+# Napoleon settings
+napoleon_google_docstring = False
+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,14 @@
+name: openmm-cookbook
+channels:
+  - conda-forge
+dependencies:
+  - python
+  - pip
+  - sphinx
+  - openmm
+  - pydata-sphinx-theme
+  - pip:
+    - m2r2
+
+
+

doc/index.rst

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

doc/userguide.rst

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