Skip to content

docs: Bring documentation (fully) up to date#615

Open
bencap wants to merge 2 commits intorelease-2026.2.0from
docs/bencap/249/bring-docs-up-to-date
Open

docs: Bring documentation (fully) up to date#615
bencap wants to merge 2 commits intorelease-2026.2.0from
docs/bencap/249/bring-docs-up-to-date

Conversation

@bencap
Copy link
Collaborator

@bencap bencap commented Jan 27, 2026

reopens the erroneously closed #609. This PR fills in incomplete pages which were punted as part of #613.

@bencap bencap marked this pull request as draft January 27, 2026 18:07
@bencap bencap linked an issue Feb 3, 2026 that may be closed by this pull request
Base automatically changed from release-2025.6.0 to main February 6, 2026 19:08
Add MkDocs Material documentation site under docs/ with full content
covering Getting Started, Finding Data, Submitting Data, MaveMD,
Programmatic Access, Reference, Troubleshooting, FAQ, and Citations.
Enhance docs with screenshots, Mermaid diagrams, admonitions,
abbreviation tooltips, code copy buttons, and instant navigation.

Add scripts/build-docs.sh to build MkDocs and copy output to
public/docs/mavedb/ for inclusion in the Vite production bundle.
Docs are served at /docs/mavedb/ to match the legacy Sphinx URL
path. The build script runs automatically in npm run build and
npm run preview. Add npm run docs for local docs development.

Update all Vue component doc links in ScoreSetCreator and
DocumentationView to point to the new /docs/mavedb/ paths.

Remove old Sphinx HTML files from public/docs/mavedb/, RST sources
from src/docs/, Sphinx dependencies from requirements.txt, and
.doctrees entry from .gitignore.
@bencap
Copy link
Collaborator Author

bencap commented Feb 27, 2026

Summary

  • Migrate documentation from Sphinx/RST to MkDocs Material with full content covering all MaveDB features across 30+ pages organized into Getting Started, Finding Data, Submitting Data, MaveMD, Programmatic Access, and Reference sections
  • Add build pipeline (scripts/build-docs.sh) that builds MkDocs and copies output to public/docs/mavedb/ for Vite bundling; runs automatically in npm run dev, build, and preview
  • Add npm run docs script for local docs development with hot-reload
  • Use use_directory_urls: false for compatibility with S3/CloudFront and Vite dev server
  • Update all Vue component doc links (ScoreSetCreator, DocumentationView) to new /docs/mavedb/ paths
  • Enhance docs with MkDocs Material features: screenshots, Mermaid diagrams, admonitions, abbreviation tooltips (glossary), code copy buttons, instant navigation, and content tooltips
  • Remove old Sphinx HTML files, RST sources, and Sphinx dependencies

Test plan

  • Run npm run dev and verify docs load at https://127.0.0.1:8081/docs/mavedb/index.html
  • Navigate between docs pages and verify internal links work
  • Verify Vue app doc links in score set creation wizard point to correct pages
  • Run npm run build and verify docs are included in dist/docs/mavedb/
  • Run npm run docs and verify MkDocs dev server starts
  • Spot-check screenshots, Mermaid diagrams, admonitions, and abbreviation tooltips render correctly
  • Verify old Sphinx URLs (/docs/mavedb/record_types.html, etc.) no longer conflict

AI Involvement

  • Model: Claude Opus 4.6

@bencap bencap marked this pull request as ready for review February 27, 2026 04:57
@bencap
Copy link
Collaborator Author

bencap commented Feb 27, 2026

We might consider removing built docs from source control, given we already track content in the /docs directory, which will deterministically build content in /public/docs/mavedb.

@bencap bencap changed the base branch from main to release-2026.1.1 February 27, 2026 17:02
Base automatically changed from release-2026.1.1 to main March 2, 2026 23:50
@bencap bencap changed the base branch from main to release-2026.2.0 March 3, 2026 00:32
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.

Update MaveDB Documentation

1 participant