Skip to content

Documentation and deployment

The site is built with Material for MkDocs, source-derived API documentation, and a small Pyodide worker. Markdown and the runtime are versioned beside the library. GitHub Pages serves the generated static files.

Build and preview

From the repository root, with Python 3.12 or newer:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e . -r requirements-docs.txt
python scripts/check_docs.py
python -m mkdocs build --strict
python -m mkdocs serve

Open the printed address (usually http://127.0.0.1:8000). Use an HTTP server, rather than opening an HTML file directly: web workers and fixture downloads need HTTP. site/ is generated and ignored by Git. The browser payload and downloadable sample files are also generated and ignored.

Publish on GitHub Pages

The site is published at EChung0111.github.io/matmalib-docs. Its generated files live in the public matmalib-docs repository. Edit the Markdown, runtime, and library in marianski-lab/matmalib; the hosting repository contains build output and a hosting README. Each publishing commit identifies the source commit used for the build.

The source repository's .github/workflows/docs.yml validates the library and every runnable example, builds the site strictly, and uploads a github-pages artifact. After these checks pass on main, its deployment job downloads that artifact and synchronizes the generated files to the hosting repository's main branch. It preserves the hosting repository's Git history and README. Pull requests run validation and upload an artifact without publishing.

In the hosting repository, Settings → Pages → Build and deployment uses Deploy from a branch, with branch main and folder / (root). GitHub Pages publishes each update to that branch. The generated .nojekyll file keeps the prebuilt site intact. Pages does not need to be enabled in the source repository. See GitHub's publishing-source documentation.

The public output includes the documented Python source, the browser runtime bundle, and the public XYZ fixtures used by the interactive examples. It contains generated documentation rather than a copy of the source repository's commit history. Review additions to the build inputs with their public destination in mind.

Publishing access and maintenance

The deployment job uses DOCS_DEPLOY_KEY, an Actions repository secret in marianski-lab/matmalib. Its corresponding SSH public key is installed as a deploy key with write access on EChung0111/matmalib-docs. This credential is dedicated to the hosting repository; the workflow's built-in token retains only contents: read access. The checkout action removes its local SSH credentials when the job ends.

To rotate the credential, generate a new SSH key pair, add the public key under the hosting repository's Settings → Deploy keys with Allow write access, and replace the source repository's DOCS_DEPLOY_KEY secret with the private key. After a successful deployment, remove the old deploy key. Keep the private key out of repository files. Creating a repository Actions secret requires write access to the source repository; managing the hosting repository's deploy keys requires administrator access.

To republish the current main branch after resolving a deployment issue, run Documentation from the source repository's Actions tab, or use:

gh workflow run docs.yml --repo marianski-lab/matmalib --ref main

Check both the source repository's Documentation run and the hosting repository's pages build and deployment run. The source workflow also waits for the public source-commit.txt to match the published source commit. If the hosting owner or repository changes, update site_url and repo_url in mkdocs.yml, the deployment target, and site links. The site's GitHub link opens the public hosting repository; contributors edit the documentation in the source repository.

Add a tutorial

Put Markdown in docs/learn/ and add it to the navigation in mkdocs.yml. A tutorial should explain its inputs and units, show a working result, interpret it, suggest a meaningful change, and state relevant limitations.

Use a fence named pyodide for a fully standalone live Python example:

```pyodide
from matmalib import Glycan
molecule = Glycan.from_file("data/glucose.xyz")
print(molecule.identify_sugars())
```

Use python for local-only code that needs a user's files, a notebook display, or an external executable. Each live cell must import its own dependencies and create its own variables. Four public XYZ fixtures are bundled at data/.... Do not include paths to private lab data.

python scripts/check_docs.py executes every live fence in its own temporary directory with the fixtures and fresh Python globals, verifies figure rendering, and checks API coverage. CI runs this against the current source.

CI also executes the shipped worker and every live example in the actual Pyodide WebAssembly runtime under Node.js. This catches differences in scientific package versions, checks PNG outputs and downloads, and exercises error recovery and variable isolation. To run it locally after building the site, use Node.js 22 or newer:

npm install --prefix /tmp/matmalib-docs-runtime pyodide@0.29.3
node scripts/check_pyodide.mjs /tmp/matmalib-docs-runtime/node_modules/pyodide/pyodide.mjs

This is a runtime integration test, not a visual browser test; it does not verify layout or browser controls. The initial run downloads Python's scientific dependencies from the pinned distribution.

Browser implementation

  • scripts/docs_hooks.py copies this checkout's Python source and public fixtures into a ZIP on every build.
  • The same hook renders MLMD default tables from dataclass fields declared or overridden by each class. Keep the explanatory prose in reference/mlmd-config.md aligned with the implementation.
  • docs/assets/playground.js supplies accessible editors, controls, status, downloads, and output handling.
  • docs/assets/python-worker.js loads the pinned runtime and executes Python outside the UI thread.
  • docs/assets/styles.css provides the layout and light/dark visual design.
  • docs/reference/api.md explicitly inventories supported public objects, with signatures and source rendered by mkdocstrings.

Dependencies load on demand. Run cancellation terminates the worker, so it also works for infinite loops without requiring special cross-origin headers. This matters on GitHub Pages. Code, tracebacks, and filenames are displayed as text, not inserted as HTML. Matplotlib plots are rendered as PNG data URLs; output downloads use blob URLs.

When changing the runner, test loading, a numerical example, a plot, a generated file, an edited cell, a Python exception, Stop, Reset, keyboard focus, and a page under a /matmalib-docs/ URL prefix. Also inspect a narrow viewport and both color modes. Keep the browser guide accurate about runtime limitations.