Skip to content

Documentation Refactor and Translation Fixes - #167

Open
cwu137 wants to merge 18 commits into
qboson:mainfrom
cwu137:main
Open

Documentation Refactor and Translation Fixes#167
cwu137 wants to merge 18 commits into
qboson:mainfrom
cwu137:main

Conversation

@cwu137

@cwu137 cwu137 commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR comprehensively revises the documentation to improve clarity, expand coverage, and fix translation errors. It includes:

  1. Getting Started rewrite : The introduction, background, installation, and quickstart pages are fully rewritten from Chinese to English and significantly expanded (net +700 lines). The landing page (index.md) is restructured as an English overview with navigation, and its tutorial section is rewritten as a Recommended Learning Paths three-path guide (Beginner / Advanced / Complete) aligned with the actual tutorial chapter order.

  2. Theoretical Foundations updates : The index page is transformed from a bare toctree into a structured English landing page with per‑chapter links and a bibliography. Two redundant section headings are cleaned up in stat-noise.md and stat-renormalization.md.

  3. Tutorials restructure : Tutorials are promoted to a top-level section in docs/index.md. tutorials/index.md is rewritten as a course-syllabus landing page (Quantum Sampling + Tutorial 1–3 + Coming Soon), removing the redundant overview table and learning paths. Two placeholder pages are added for upcoming tutorials:

    • qvae_cell.md – Q-VAE for single-cell transcriptomics
    • qdiffusion.md – Q-Diffusion for protein sequence generation
  4. Build & docs configuration : conf.py is updated (hardcoded version, KaTeX/Mermaid/BibTeX support), a new refs.bib is added, and docs/README.md reflects the updated structure, build steps, and TODO checklist.

  5. Translation sync & fixes : All 61 .po files are synchronised with the rewritten sources. Numerous misplaced, duplicated, or truncated translations (especially in the theoretical-foundations and modules catalogs) are corrected, and missing translations (e.g., in introduction.po and quickstart.po) are added. Stale entries in introduction, quickstart, and modules catalogs are marked obsolete.

  6. Contributing link fix : A broken relative link to example/README_ZH.md (outside the Sphinx source tree, causing a myst.xref_missing warning) is replaced with the GitHub blob URL.

  7. README.md TODO checklist update : The docs/README.md now contains an updated to‑do list that marks the "Getting Started" and "Theoretical Foundations index" sections as completed, and adds new items for tutorials, advanced examples, FAQ, and release notes (see below).

Key Changes

Area Files What changed
Getting Started 5 source + 2 .po Rewritten to English, expanded; tutorial section → Recommended Learning Paths
Theoretical Foundations 3 source Index rebuilt as landing page; headings cleaned
Tutorials 1 index + 2 new source + 6 .po Promoted to top-level; index restructured; qvae_cell / qdiffusion placeholders added
Build & docs conf.py, refs.bib, README.md Extensions, BibTeX, structure & TODO updated
Translations 61 .po Full sync; 9 misaligned files fixed; stale entries marked obsolete
README 1 markdown directory structure and To-Do list updated
Contributing 1 source + 2 .po Out-of-tree link → GitHub URL

Verification

  • sphinx -M gettext, no missing or empty strings in both zh_CN and en catalogs (excluding 14 known dead files under source/kpp-theoretical-foundations/).
  • .mo compilation, successful for all catalogs.
  • make html (zh_CN + en), builds successfully with 0 warnings; spot-checked translations render correctly (e.g., energy function decomposition, positive phase PyTorch step, sidebar tutorial entries).
  • Sidebar check: all 9 tutorial pages (including the two new placeholders) appear in both language builds.

To Do (Future Work)

The following items remain for subsequent documentation improvements:

  • Enrich existing tutorials: Add more step-by-step commentary and expected-output explanations to the Quantum Sampling chapters and Tutorials 1–3 (BM generation, RBM/DBN classification, Q-VAE MNIST).
  • Expand placeholder tutorials: Fill in qvae_cell.md (single-cell transcriptomics Q-VAE) and qdiffusion.md (protein sequence Q-Diffusion) from placeholders to full hands-on guides, based on the notebooks/scripts in example/qvae_cell/ and example/qdiffusion/.
  • Proofread Chinese translations in the Theoretical Foundations pages (all chapters) to ensure accuracy and consistency.
  • Add advanced feature documentation (e.g., advanced_features.md) for expert users.
  • Supplement the FAQ with more common questions and answers. 
  • Update release notes (release_notes.md) to reflect the latest version and changes.

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