From 60211598cdb4f9c16c591c1e97cbaff46e545b9a Mon Sep 17 00:00:00 2001 From: SimonBoothroyd Date: Fri, 1 Dec 2023 08:39:55 -0500 Subject: [PATCH 1/2] Add initial documentation --- .github/workflows/ci.yaml | 1 + .github/workflows/docs.yaml | 51 +++++++++++++ Makefile | 11 ++- README.md | 60 +++++----------- devtools/envs/base.yaml | 11 +++ docs/development.md | 28 ++++++++ docs/examples | 1 + docs/index.md | 1 + docs/javascripts/mathjax.js | 16 +++++ docs/scripts/gen_ref_pages.py | 39 ++++++++++ mkdocs.yml | 130 ++++++++++++++++++++++++++++++++++ smee/geometry.py | 2 +- 12 files changed, 306 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/development.md create mode 120000 docs/examples create mode 100644 docs/index.md create mode 100644 docs/javascripts/mathjax.js create mode 100644 docs/scripts/gen_ref_pages.py create mode 100644 mkdocs.yml diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 3c98f51..cfcb27b 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -25,6 +25,7 @@ jobs: make lint make test make test-examples + make docs-build - name: CodeCov uses: codecov/codecov-action@v3.1.1 diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..28e2297 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,51 @@ +name: Publish Documentation + +on: + push: + branches: + - main + tags: + - '*' + +jobs: + deploy-docs: + + runs-on: ubuntu-latest + container: condaforge/mambaforge:latest + + steps: + - name: Prepare container + run: | + apt update && apt install -y git make + + - name: Checkout + uses: actions/checkout@v3.3.0 + + - name: Determine Version + shell: bash + run: | + if [ "$GITHUB_REF" = "refs/heads/main" ]; then + echo "VERSION=latest" >> $GITHUB_ENV + elif [ "${GITHUB_REF#refs/tags/}" != "$GITHUB_REF" ]; then + VERSION=$(echo $GITHUB_REF | sed 's/refs\/tags\///') + echo "VERSION=$VERSION stable" >> $GITHUB_ENV + else + echo "Invalid ref: $GITHUB_REF" + exit 1 + fi + + - name: Build and Deploy Documentation + run: | + git config --global user.name 'GitHub Actions' + git config --global user.email 'actions@github.com' + git config --global --add safe.directory "$PWD" + git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} + + git fetch --all --prune + + make env + + pip install git+https://${INSIDER_DOCS_TOKEN}@github.com/SimonBoothroyd/griffe-pydantic.git@fix-inheritence-static + pip install git+https://${INSIDER_DOCS_TOKEN}@github.com/SimonBoothroyd/mkdocstrings-python.git + + make docs-deploy VERSION="$VERSION" diff --git a/Makefile b/Makefile index f0ae9b0..cf410b4 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ CONDA_ENV_RUN := conda run --no-capture-output --name $(PACKAGE_NAME) EXAMPLES_SKIP := examples/md-simulations.ipynb EXAMPLES := $(filter-out $(EXAMPLES_SKIP), $(wildcard examples/*.ipynb)) -.PHONY: pip-install env lint format test test-examples +.PHONY: pip-install env lint format test test-examples docs-build docs-deploy pip-install: $(CONDA_ENV_RUN) pip install --no-build-isolation --no-deps -e . @@ -36,3 +36,12 @@ test: test-examples: $(CONDA_ENV_RUN) jupyter nbconvert --to notebook --execute $(EXAMPLES) + +docs-build: + $(CONDA_ENV_RUN) mkdocs build + +docs-deploy: +ifndef VERSION + $(error VERSION is not set) +endif + $(CONDA_ENV_RUN) mike deploy --push --update-aliases $(VERSION) diff --git a/README.md b/README.md index 07cf028..cc6ede1 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,20 @@ -SMIRNOFF Energy Evaluations -=========================== -[![Test Status](https://github.com/simonboothroyd/smee/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/simonboothroyd/smee/actions/workflows/ci.yaml) -[![codecov](https://codecov.io/gh/simonboothroyd/smee/branch/main/graph/badge.svg)](https://codecov.io/gh/simonboothroyd/smee/branch/main) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +

SMIRNOFF Energy Evaluations

+ +

Differentiably evaluate energies of molecules using SMIRNOFF force fields

+ +

+ + ci + + + coverage + + + license + +

+ +--- The `smee` framework aims to offer a simple API for differentiably evaluating the energy of [SMIRNOFF](https://openforcefield.github.io/standards/standards/smirnoff/) force fields applied to molecules using `pytorch`. @@ -15,10 +27,6 @@ The package currently supports evaluating the energy of force fields that contai parameter handlers in addition to limited support for registering custom handlers. -***Warning**: This code is currently experimental and under active development. If you are using this it, please be -aware that it is not guaranteed to provide correct results, the documentation and testing maybe be incomplete, and the -API can change without notice.* - ## Installation This package can be installed using `conda` (or `mamba`, a faster version of `conda`): @@ -37,40 +45,6 @@ mamba install -c conda-forge jupyter nglview "smirnoff-plugins >=0.0.4" To get started, see the [examples](examples). -## Development - -A development conda environment can be created and activated by running: - -```shell -make env -conda activate smee -``` - -The environment will include all example and development dependencies, including linters and testing apparatus. - -Unit / example tests can be run using: - -```shell -make test -make test-examples -``` - -The codebase can be formatted by running: - -```shell -make format -``` - -or checked for lint with: - -```shell -make lint -``` - -## License - -The main package is release under the [MIT license](LICENSE). - ## Copyright Copyright (c) 2023, Simon Boothroyd diff --git a/devtools/envs/base.yaml b/devtools/envs/base.yaml index 24865cd..9586dfc 100644 --- a/devtools/envs/base.yaml +++ b/devtools/envs/base.yaml @@ -50,3 +50,14 @@ dependencies: - pytest-mock - codecov + + # Docs + - mkdocs + - mkdocs-material + - mkdocs-gen-files + - mkdocs-literate-nav + - mkdocs-jupyter + - mkdocstrings + - mkdocstrings-python + - black + - mike diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..c89ad21 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,28 @@ +# Development + +To create a development environment, you must have [`mamba` installed](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html). + +A development conda environment can be created and activated with: + +```shell +make env +conda activate smee +``` + +To format the codebase: + +```shell +make format +``` + +To run the unit tests: + +```shell +make test +``` + +To serve the documentation locally: + +```shell +mkdocs serve +``` diff --git a/docs/examples b/docs/examples new file mode 120000 index 0000000..a6573af --- /dev/null +++ b/docs/examples @@ -0,0 +1 @@ +../examples \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..612c7a5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +--8<-- "README.md" diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 0000000..06dbf38 --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.typesetPromise() +}) diff --git a/docs/scripts/gen_ref_pages.py b/docs/scripts/gen_ref_pages.py new file mode 100644 index 0000000..63c9d67 --- /dev/null +++ b/docs/scripts/gen_ref_pages.py @@ -0,0 +1,39 @@ +"""Generate the code reference pages and navigation.""" + +import pathlib + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() +src = pathlib.Path(__file__).parent.parent.parent / "smee" + +mod_symbol = '' + +for path in sorted(src.rglob("*.py")): + if "tests" in str(path): + continue + + module_path = path.relative_to(src.parent).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = pathlib.Path("reference", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1].startswith("_"): + continue + + nav_parts = [f"{mod_symbol} {part}" for part in parts] + nav[tuple(nav_parts)] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"::: {ident}") + + mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8628ebb --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,130 @@ +site_name: "smee" +site_description: "Differentiably evaluate energies of molecules." +site_url: "https://github.com/SimonBoothroyd/smee" +repo_url: "https://github.com/SimonBoothroyd/smee" +repo_name: "SimonBoothroyd/smee" +site_dir: "site" +watch: [mkdocs.yml, README.md, smee/, docs] +copyright: Copyright © 2023 Simon Boothroyd +edit_uri: edit/main/docs/ + +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + +nav: +- Home: + - Overview: index.md +- Examples: + - examples/README.md + - examples/compute-energy.ipynb + - examples/conformer-minimization.ipynb + - examples/custom-handler.ipynb + - examples/md-simulations.ipynb + - examples/parameter-gradients.ipynb +- API reference: reference/ +- Development: development.md + +theme: + name: material + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.indexes + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - search.highlight + - search.suggest + - toc.follow + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: purple + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: lime + toggle: + icon: material/weather-night + name: Switch to system preference + +markdown_extensions: +- attr_list +- def_list +- admonition +- footnotes +- pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.inlinehilite +- pymdownx.superfences +- pymdownx.magiclink +- pymdownx.snippets: + base_path: [!relative $config_dir] + check_paths: true +- pymdownx.details +- pymdownx.arithmatex: + generic: true +- pymdownx.tabbed: + alternate_style: true +- toc: + permalink: "#" + +plugins: +- autorefs +- search +- gen-files: + scripts: + - docs/scripts/gen_ref_pages.py +- mkdocs-jupyter: + include: [ "examples/*.ipynb" ] +- literate-nav: + nav_file: SUMMARY.md +- mkdocstrings: + handlers: + python: + paths: [smee/] + options: + extensions: + - griffe_pydantic: + schema: false + docstring_options: + ignore_init_summary: true + returns_multiple_items: false + returns_named_value: false + docstring_section_style: list + filters: ["!^_"] + heading_level: 1 + inherited_members: true + merge_init_into_class: true + separate_signature: true + show_root_heading: true + show_root_full_path: false + show_signature_annotations: true + show_symbol_type_heading: true + show_symbol_type_toc: true + signature_crossrefs: true + summary: true + members_order: source + +extra_javascript: + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js diff --git a/smee/geometry.py b/smee/geometry.py index b545b58..d18a26e 100644 --- a/smee/geometry.py +++ b/smee/geometry.py @@ -334,7 +334,7 @@ def add_v_site_coords( v_sites: "smee.VSiteMap", conformer: torch.Tensor, force_field: "smee.TensorForceField", -): +) -> torch.Tensor: """Appends the coordinates of any virtual sites to a conformer (or batch of conformers) containing only atomic coordinates. From 104d82522947b7e546afefd490579fd8f06fc53d Mon Sep 17 00:00:00 2001 From: SimonBoothroyd Date: Fri, 1 Dec 2023 17:41:59 -0500 Subject: [PATCH 2/2] Disable private extension by default --- .github/workflows/docs.yaml | 2 ++ mkdocs.yml | 4 +--- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 28e2297..82f41a5 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -48,4 +48,6 @@ jobs: pip install git+https://${INSIDER_DOCS_TOKEN}@github.com/SimonBoothroyd/griffe-pydantic.git@fix-inheritence-static pip install git+https://${INSIDER_DOCS_TOKEN}@github.com/SimonBoothroyd/mkdocstrings-python.git + sed -i 's/# extensions/extensions/' mkdocs.yml + make docs-deploy VERSION="$VERSION" diff --git a/mkdocs.yml b/mkdocs.yml index 8628ebb..55ee59e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -102,9 +102,7 @@ plugins: python: paths: [smee/] options: - extensions: - - griffe_pydantic: - schema: false + # extensions: [ griffe_pydantic ] docstring_options: ignore_init_summary: true returns_multiple_items: false