Skip to content

Add API docs built with mkdocs and deployed to GitHub Pages - #32

Merged
aarmey merged 2 commits into
mainfrom
docs/mkdocs-github-pages
Aug 26, 2026
Merged

Add API docs built with mkdocs and deployed to GitHub Pages#32
aarmey merged 2 commits into
mainfrom
docs/mkdocs-github-pages

Conversation

@aarmey

@aarmey aarmey commented Aug 26, 2026

Copy link
Copy Markdown
Member

Summary

  • Add mkdocs + Material theme + mkdocstrings to render valentbind's docstrings into a browsable API reference (docs/api.md), plus a landing page (docs/index.md) with install/usage instructions.
  • .github/workflows/docs.yml builds the site with mkdocs build --strict on every push to main and deploys it to GitHub Pages via the official upload-pages-artifact/deploy-pages actions.
  • Enabled GitHub Pages on the repo with build_type: workflow (via the API) so this workflow has somewhere to publish to — site will be live at https://meyer-lab.github.io/valentBind/ once this merges and the workflow runs on main.
  • Docs render fine against the current (pre-Add descriptive docstrings and full type annotations #30) docstrings; they'll get nicer once Add descriptive docstrings and full type annotations #30's Sphinx-style :param:/:return: docstrings land, since mkdocstrings is configured for that style.

Test plan

  • uv run mkdocs build --strict succeeds with no warnings
  • uv run ruff check . / uv run ruff format --check . pass
  • uv run pytest still passes

- mkdocs + Material theme + mkdocstrings render valentbind's
  docstrings into a browsable API reference, plus a landing page with
  install/usage instructions.
- .github/workflows/docs.yml builds the site with `mkdocs build
  --strict` and deploys it to GitHub Pages via the official
  upload-pages-artifact/deploy-pages actions on every push to main.
- Add mkdocs, mkdocs-material, and mkdocstrings[python] to the dev
  dependency group.
Resolves conflicts from #26-#31/#33 landing on main first: kept both
the ruff and mkdocs additions to the dev dependency group, and
regenerated uv.lock from scratch rather than hand-editing it.
@aarmey
aarmey merged commit ed4d74a into main Aug 26, 2026
2 checks passed
@aarmey
aarmey deleted the docs/mkdocs-github-pages branch August 26, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant