update conf and workflow

.gitignore

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

doc/Makefile

@@ -17,4 +17,10 @@ help:
 # 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://sef43.github.io/openmm-ml/dev/"
+    }
+]

doc/api.rst → doc/api.rst.jinja2

@@ -3,22 +3,27 @@ API
 
 .. autosummary::
     :toctree: generated/
+    :nosignatures:
 
     openmmml.MLPotential
 
 
-Models
-~~~~~~
-.. autosummary::
-    :toctree: generated/
-
-    openmmml.models.anipotential.ANIPotentialImpl
-
-
 Developer API
 ~~~~~~~~~~~~~
 .. autosummary::
     :toctree: generated/
+    :nosignatures:
 
     openmmml.mlpotential.MLPotentialImplFactory
-    openmmml.mlpotential.MLPotentialImpl
+    openmmml.mlpotential.MLPotentialImpl
+
+
+Models
+~~~~~~
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    {% for model in models %}
+      {{ model }}
+    {% endfor %}

doc/conf.py

@@ -2,20 +2,47 @@
 
 import os
 import sys
+import openmmml
+import pkg_resources
+import git
+
 
 sys.path.append(os.path.abspath('../'))
 
-release = os.getenv("PAGES_DEPLOY_PATH","dev").lstrip("refs/tags/")
 
-print(release)
+
+# 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",
-    # "process-docstring",
     'm2r2'
 ]
 
@@ -29,7 +56,7 @@
 source_suffix = ".rst"
 master_doc = "index"
 
-project = u"OpenMM ML Docs"
+project = u"OpenMM ML"
 copyright = u"2023, Stanford University and the Authors"
 
 
@@ -54,64 +81,23 @@
       {"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,
-    },
+    "github_url": "https://github.com/openmm/openmm-ml"
+}
 
-    "check_switcher": False,
 
-    "navbar_start": ["navbar-logo", "version-switcher"],
+# settings for version switcher and warning
+html_theme_options["navbar_start"]=["navbar-logo", "version-switcher"]
+html_theme_options["switcher"]= {
+        "json_url": "https://sef43.github.io/openmm-ml/dev/_static/versions.json",
+        "version_match": version_match,
+    }
 
-    "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",
-#     ]
-# }
+#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 = False
+napoleon_google_docstring = True
 napoleon_numpy_docstring = True
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = True

doc/environment.yml

@@ -9,6 +9,7 @@ dependencies:
   - pydata-sphinx-theme
   - pip:
     - m2r2
+    - GitPython
 
 
 

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()