Documentation Refactor and Translation Fixes - #167
Open
cwu137 wants to merge 18 commits into
Open
Conversation
Documentation Refactor and Translation Fixes
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR comprehensively revises the documentation to improve clarity, expand coverage, and fix translation errors. It includes:
Getting Started rewrite : The
introduction,background,installation, andquickstartpages 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.Theoretical Foundations updates : The
indexpage 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 instat-noise.mdandstat-renormalization.md.Tutorials restructure : Tutorials are promoted to a top-level section in
docs/index.md.tutorials/index.mdis 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 transcriptomicsqdiffusion.md– Q-Diffusion for protein sequence generationBuild & docs configuration :
conf.pyis updated (hardcoded version, KaTeX/Mermaid/BibTeX support), a newrefs.bibis added, anddocs/README.mdreflects the updated structure, build steps, and TODO checklist.Translation sync & fixes : All 61
.pofiles are synchronised with the rewritten sources. Numerous misplaced, duplicated, or truncated translations (especially in thetheoretical-foundationsandmodulescatalogs) are corrected, and missing translations (e.g., inintroduction.poandquickstart.po) are added. Stale entries inintroduction,quickstart, andmodulescatalogs are marked obsolete.Contributing link fix : A broken relative link to
example/README_ZH.md(outside the Sphinx source tree, causing amyst.xref_missingwarning) is replaced with the GitHub blob URL.README.md TODO checklist update : The
docs/README.mdnow 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
Verification
sphinx -M gettext, no missing or empty strings in bothzh_CNandencatalogs (excluding 14 known dead files undersource/kpp-theoretical-foundations/)..mocompilation, 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).To Do (Future Work)
The following items remain for subsequent documentation improvements:
qvae_cell.md(single-cell transcriptomics Q-VAE) andqdiffusion.md(protein sequence Q-Diffusion) from placeholders to full hands-on guides, based on the notebooks/scripts inexample/qvae_cell/andexample/qdiffusion/.advanced_features.md) for expert users.release_notes.md) to reflect the latest version and changes.