Skip to content

Switch documentation to MkDocs Material and dynamically generate tutorial figures (#516) - #518

Merged
aarmey merged 1 commit into
mainfrom
issue-516-mkdocs-migration
Aug 28, 2026
Merged

aarmey merged 1 commit into
mainfrom
issue-516-mkdocs-migration

Conversation

@aarmey

@aarmey aarmey commented Aug 27, 2026

Copy link
Copy Markdown
Member

Closes #516

Summary of Changes

  • Migrated documentation framework: Replaced Sphinx configuration and dependencies with mkdocs, mkdocs-material, and mkdocstrings[python].
  • Created MkDocs Configuration: Configured mkdocs.yml with Material theme, palette toggle (light/dark), code-copying, navigation features, and mkdocstrings with NumPy docstring support.
  • Converted Documentation to Markdown:
    • docs/index.rst -> docs/index.md
    • docs/tutorial.rst -> docs/tutorial.md
    • docs/api.rst -> docs/api.md
    • docs/references.rst -> docs/references.md
  • Dynamic Tutorial Figures:
    • Configured docs/generate_tutorial_figures.py as an MkDocs build hook (on_pre_build) to dynamically generate tutorial figures (steps 5–10: condition factors, cell embeddings, eigenstate factors, gene factors, gene expression, and weighted projections).
    • Preserved precomputed static scans (step2_r2x.png and step3_fms.png) in docs/assets/tutorial_images/.
  • Cleaned Repository Assets:
    • Removed Sphinx config (docs/conf.py) and old static images in docs/_static/.
    • Updated .gitignore to ignore dynamically generated tutorial figures and the site/ build directory.
  • Updated CI/CD:
    • Updated .github/workflows/documentation.yml to build docs via uv run --group docs mkdocs build and deploy the site artifact to GitHub Pages.

@aarmey
aarmey merged commit 0002052 into main Aug 28, 2026
2 checks passed
@aarmey
aarmey deleted the issue-516-mkdocs-migration branch August 28, 2026 03:46
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.

Switch documentation to MkDocs Material and dynamically generate tutorial figures

1 participant