Publish docs/ as a versioned MkDocs site at docs.cdotlib.org

[davmlaw]

🤖 Written by Claude

Summary

Publish the existing in-repo docs/ directory as a rendered, versioned documentation site using MkDocs (mkdocs-material), deployed to GitHub Pages via mkdocs gh-deploy, with a CNAME to docs.cdotlib.org.

Not a paper blocker. The docs/ content is already versioned with the code and citable via tagged repo permalinks, which is sufficient for the paper's availability statement. This issue is presentation/discoverability polish to be done after the paper, not before submission.

Background

The original motivation was that the GitHub wiki is not versioned with the code and isn't citable. That defect is already fixed: the source material now lives in docs/ (schema, biocommons/PyHGVS examples, version-safety write-up, JSON data format, coordinates/exons, release files, create-from-scratch, etc.) with an index at docs/README.md. What's missing is a rendered site at a stable, branded URL.

What to do

• Add mkdocs.yml configuring the mkdocs-material theme over the existing docs/ tree.
• Build a nav structure from the existing pages (index / quickstart / data files / clean-hgvs / canonical / REST API / data format / data generation).
• Deploy to GitHub Pages via mkdocs gh-deploy (or a GitHub Actions workflow on tag/release).
• Add a CNAME for docs.cdotlib.org and configure DNS (same ownership as the existing cdotlib.org REST site).
• Once live, decide whether the paper's availability statement should print the docs.cdotlib.org URL or keep the GitHub repo link.

Notes

• cdotlib.org already exists for the REST server (SACGF/cdot_rest), so a docs. subdomain is the natural home.
• Keep docs versioned with code; consider mike for per-version docs if needed later.

[davmlaw]

🤖 Written by Claude

Detailed page structure carried over from the planning doc (the docs/ source files map onto these):

• index.md — what cdot is, one-minute install + example
• quickstart.md — biocommons/hgvs integration, PyHGVS integration, full working code
• data-files.md — how to get JSON.gz files (GitHub releases, data_release.py)
• clean-hgvs.md — clean_hgvs() and get_best_transcript_version() with examples
• canonical.md — gene-symbol HGVS resolution (resolve_gene_hgvs / fix_hgvs), get_tx_ac_tags_for_gene tag ranking, MANE, resolving gene-only HGVS (Canonical transcripts  #36)
• rest-api.md — cdotlib.org endpoints, RESTDataProvider
• data-format.md — JSON schema, exon 6-tuple, gap encoding (for tool authors)
• data-generation.md — building your own JSON.gz from RefSeq/Ensembl GTF/GFF3; Snakemake pipeline; source priority; adding a genome build or species (Choice of transcript version has changed (NM_001017995.2 uses UTA 20241220) #95)

Note: data-generation.md matters for users with non-human organisms or custom assemblies who need to run the pipeline themselves.