Add initial documentation (#61)

.github/workflows/ci.yaml

@@ -24,6 +24,7 @@ jobs:
         make env
         make lint
         make test
+        make docs-build
 
     - name: CodeCov
       uses: codecov/[email protected]

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+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/[email protected]
+
+    - 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
+      env:
+        INSIDER_DOCS_TOKEN: ${{ secrets.INSIDER_DOCS_TOKEN }}
+      run: |
+        git config --global user.name 'GitHub Actions'
+        git config --global user.email '[email protected]'
+        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
+
+        sed -i 's/# extensions/extensions/' mkdocs.yml
+
+        make docs-insiders INSIDER_DOCS_TOKEN="${INSIDER_DOCS_TOKEN}"        
+        make docs-deploy VERSION="$VERSION"

Makefile

@@ -30,3 +30,16 @@ format:
 
 test:
 	$(CONDA_ENV_RUN) pytest -v --cov=$(PACKAGE_NAME) --cov-report=xml --color=yes $(PACKAGE_NAME)/tests/
+
+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)
+
+docs-insiders:
+	$(CONDA_ENV_RUN) pip install git+https://$(INSIDER_DOCS_TOKEN)@github.com/SimonBoothroyd/mkdocstrings-python.git \
+                    			 git+https://$(INSIDER_DOCS_TOKEN)@github.com/SimonBoothroyd/griffe-pydantic.git@fix-inheritence-static

README.md

@@ -1,8 +1,20 @@
-DESCENT
-=======
-[![Test Status](https://github.com/simonboothroyd/descent/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/simonboothroyd/descent/actions/workflows/ci.yaml)
-[![codecov](https://codecov.io/gh/simonboothroyd/descent/branch/main/graph/badge.svg)](https://codecov.io/gh/simonboothroyd/descent/branch/main)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<h1 align="center">DESCENT</h1>
+
+<p align="center">Optimize force field parameters against reference data</p>
+
+<p align="center">
+  <a href="https://github.com//actions?query=workflow%3Aci">
+    <img alt="ci" src="https://github.com/SimonBoothroyd/descent/actions/workflows/ci.yaml/badge.svg" />
+  </a>
+  <a href="https://codecov.io/gh/SimonBoothroyd/descent/branch/main">
+    <img alt="coverage" src="https://codecov.io/gh/SimonBoothroyd/descent/branch/main/graph/badge.svg" />
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img alt="license" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
+  </a>
+</p>
+
+---
 
 The `descent` framework aims to offer a modern API for training classical force field parameters (either from a 
 traditional format such as SMIRNOFF or from some ML model) against reference data using `pytorch`.
@@ -32,39 +44,6 @@ mamba install -c conda-forge jupyter
 
 To get started, see the [examples](examples).
 
-## Development
-
-A development conda environment can be created and activated by running:
-
-```shell
-make env
-conda activate descent
-```
-
-The environment will include all example and development dependencies, including linters and testing apparatus.
-
-Unit / example tests can be run using:
-
-```shell
-make test
-```
-
-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

devtools/envs/base.yaml

@@ -52,3 +52,14 @@ dependencies:
   - pytest-mock
 
   - codecov
+
+  # Docs
+  - mkdocs
+  - mkdocs-material
+  - mkdocs-gen-files
+  - mkdocs-literate-nav
+  - mkdocs-jupyter
+  - mkdocstrings
+  - mkdocstrings-python
+  - black
+  - mike

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 descent
+```
+
+To format the codebase:
+
+```shell
+make format
+```
+
+To run the unit tests:
+
+```shell
+make test
+```
+
+To serve the documentation locally:
+
+```shell
+mkdocs serve
+```

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

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

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 / "descent"
+
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+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())

mkdocs.yml

@@ -0,0 +1,118 @@
+site_name: "descent"
+site_description: "Optimize force field parameters against reference data."
+site_url: "https://github.com/SimonBoothroyd/descent"
+repo_url: "https://github.com/SimonBoothroyd/descent"
+repo_name: "SimonBoothroyd/descent"
+site_dir: "site"
+watch: [mkdocs.yml, README.md, descent/, 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
+- API reference: reference/
+- Development: development.md
+
+theme:
+  name: material
+  features:
+  - announce.dismiss
+  - 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:
+    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: [descent/]
+        options:
+          # extensions: [ griffe_pydantic ]
+          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