docs: 📝 replace the MkDocs site with a Fumadocs site

[Panadestein]

🤖 AI text below 🤖

Closes #32.

What

This ports the monoprop Next.js + Fumadocs setup to docs/ and removes MkDocs: mkdocs.yml, gen_ref_pages.py, the MathJax/CSS assets and the mkdocs* packages in the docs group.

• Scaffold (docs/src, configs, package.json/package-lock.json): copied from monoprop. It keeps the Algorithmiq branding: the GT-Planar font, the teal accent and the logo. Changes for this repo:
  • The umami analytics snippet is removed (it had monoprop's site id).
  • basePath and trailingSlash are set, because the site is served at algorithmiq.github.io/src-method/. basePath comes from NEXT_PUBLIC_BASE_PATH and is empty for npm run dev. The static search index and the "Copy Markdown" URLs get the prefix too.
  • metadataBase is set for the Open Graph images.
• MDX pages (docs/content/docs/):
  • Landing page and Getting Started.
  • Concepts: the algorithm, plus the index and contraction conventions.
  • Features: stacks, cutoff, precision and seeding, GPU, logging.
  • Benchmarks: a summary of benches/.
  • References: a BibTeX bibliography with the SRC paper, Halko–Martinsson–Tropp and quimb.
  • Contributing: workflow, testing, documenting, dependencies, versioning, SonarCloud.
  • The old docs/developer-guide/*.md pages were template leftovers that mentioned "aurora", setuptools-scm and pytest plugins we don't use. I rewrote them for this repo.
• API reference: gen_api_dump.py (griffe → JSON) and generate-api.mjs (JSON → MDX) generate it from the docstrings of stack, apply and compress. Compared with monoprop's scripts:
  • Raises: sections are rendered instead of dropped.
  • *args no longer show = () and pick up their *name docstring entry.
  • Signatures no longer get a spurious / after *args.
  • < and { are no longer escaped inside code spans, where the escape showed up as \<psi|.
  • Module-level logger/constants are hidden.
• Tutorials: notebooks_to_mdx.py executes each docs/notebooks/<name>/<name>.ipynb; any cell error fails the build. There is one tutorial, Accuracy versus bond dimension, which compares SRC against contract-then-SVD as chi_out grows and runs in about 10 s.
• Citations: [@key] links pointed at a #bib-… anchor on the current page, which only exists on the references page (monoprop has the same bug). A small rehype pass now points them at /references#bib-….
• Workflow (docpages.yml): Python + Node 22 → generate the API → run every Python block in the prose pages with pytest --markdown-docs (blocks that can't run standalone are marked python notest) → execute the notebooks → npm run build → deploy docs/out to Pages on main.
• Tooling:
  • The docs group is now griffelib, nbconvert and pytest-markdown-docs, plus test and interactive.
  • The Nix flake and the Dev Container add Node.js 22.
  • README.md, AGENTS.md and docs/README.md explain the local preview.

Checks

• I did a clean local run of exactly the workflow's steps with NEXT_PUBLIC_BASE_PATH=/src-method.
  • The 11 page examples pass.
  • The notebook executes and next build exports 81 static pages.
  • tsc --noEmit is clean.
• I served out/ under /src-method/ and checked in headless Chromium:
  • home, an API page, a tutorial (with the inlined figure) and a KaTeX/citation page;
  • links, assets, /api/search and the markdown routes all resolve under the prefix.
• uv run prek run --all-files is clean.

Notes and follow-ups

• Conflict with chore(deps): 🔧 relax dependency floors and test them in CI #54: that PR adds a section to docs/developer-guide/dependencies.md, which this PR moves to docs/content/docs/contributing/dependencies.mdx. Whichever merges second should port that section, plus the bench group from chore(deps): 🔧 move benchmark-only dependencies to a bench group #53.
• I didn't port monoprop's post-build lychee link check or the Cloudflare PR previews. The base path breaks lychee's root-relative resolution unless it's remapped, and the previews need Cloudflare secrets. I can add either if wanted.
• After merge, check that Settings → Pages is still set to "GitHub Actions". It currently is.

[github-actions]

Test Results

  4 files  ±0    4 suites  ±0   2m 2s ⏱️ -11s
135 tests ±0  134 ✅ ±0  1 💤 ±0  0 ❌ ±0 
516 runs  ±0  514 ✅ ±0  2 💤 ±0  0 ❌ ±0 

Results for commit 8a454cc. ± Comparison against base commit 83c1d16.

♻️ This comment has been updated with latest results.