Add doc for Moonshine v2 models#806
Conversation
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for Moonshine v2 speech recognition models, including a Python generation script ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly expands the documentation for the Moonshine automatic speech recognition models by introducing a new version, Moonshine v2. This update brings multilingual capabilities, supporting a wide array of languages, and provides updated code examples across various programming languages to facilitate easier adoption and integration. The changes streamline the documentation process through automated generation and enhance user accessibility by updating the Huggingface Space instructions. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds extensive documentation for the Moonshine v2 models, including a new Python script for generating documentation pages from templates, numerous new .rst files with model details and usage examples, and updates to existing documentation to link to the new content. My review focuses on improving the new generation script for correctness and efficiency, fixing some typos in the documentation files, and addressing an indentation inconsistency in the Makefile.
| source/onnx/pretrained_models/offline-ctc/wenet/run.sh \ | ||
| source/onnx/moonshine/run.sh |
There was a problem hiding this comment.
The indentation in the SCRIPTS variable definition is inconsistent. Line 13 uses spaces, while lines 14 and 15 use tabs. For consistency, it's better to use spaces for indentation in this block.
source/onnx/pretrained_models/offline-ctc/wenet/run.sh \
source/onnx/moonshine/run.sh
| code2lang = { | ||
| "ko": "Korea", | ||
| "ja": "Japanese", | ||
| "en": "English", | ||
| "zh": "Chinese", | ||
| "vi": "Vietnamese", | ||
| "uk": "Ukrainian", | ||
| "ja": "Japanese", | ||
| "es": "Spanish", | ||
| "ar": "Arabic", | ||
| } |
There was a problem hiding this comment.
There are a couple of issues in the code2lang dictionary:
- The key
'ja'is duplicated. While this doesn't cause a runtime error, it's redundant. Please remove one of the entries. - The value for
'ko'is'Korea', which is a country name. It should be'Korean'to be consistent with other language names (e.g., 'Japanese', 'English').
code2lang = {
"ko": "Korean",
"ja": "Japanese",
"en": "English",
"zh": "Chinese",
"vi": "Vietnamese",
"uk": "Ukrainian",
"es": "Spanish",
"ar": "Arabic",
}| env = Environment(loader=FileSystemLoader(".")) | ||
| template = env.get_template(f"./tpl/model_v2.rst") |
There was a problem hiding this comment.
The Jinja2 Environment and template are being initialized inside the loop. This is inefficient as they are the same for every iteration. It's better to initialize them once before the loop starts.
For example:
def main():
# ...
env = Environment(loader=FileSystemLoader("."))
template = env.get_template(f"./tpl/model_v2.rst")
for m in models:
# ... now use env and template inside the loop| @@ -0,0 +1,16 @@ | |||
| .. _moonsine-models-v2: | |||
There was a problem hiding this comment.
There is a typo in the reference label. It should be moonshine-models-v2 instead of moonsine-models-v2.
| .. _moonsine-models-v2: | |
| .. _moonshine-models-v2: |
| @@ -1,6 +1,15 @@ | |||
| .. _moonsine-models-v1: | |||
There was a problem hiding this comment.
There is a typo in the reference label. It should be moonshine-models-v1 instead of moonsine-models-v1.
| .. _moonsine-models-v1: | |
| .. _moonshine-models-v1: |
|
|
||
| This page is for Moonshine v1, which supports only English. | ||
|
|
||
| Please see :ref:`moonsine-models-v2` for models supporting |
There was a problem hiding this comment.
There is a typo in the reference. It should be :ref:moonshine-models-v2`` to match the corrected label in models-v2.rst.
| Please see :ref:`moonsine-models-v2` for models supporting | |
| Please see :ref:`moonshine-models-v2` for models supporting |
There was a problem hiding this comment.
Pull request overview
Adds documentation scaffolding for Moonshine v2 ONNX models (multi-language) and wires generation into the docs build so the v2 model pages can be produced automatically.
Changes:
- Add a Jinja2-based generator + template to produce per-model Moonshine v2 documentation pages and include them from a new
models-v2.rst. - Extend Moonshine language-specific API example pages (C/C#/Go/Java/JS/Pascal/Python/Rust/Swift/etc.) with v2 example links.
- Update the docs build (
docs/Makefile) to run the Moonshine v2 doc generator duringmake html.
Reviewed changes
Copilot reviewed 29 out of 30 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/onnx/moonshine/tpl/model_v2.rst | New Jinja template for per-model Moonshine v2 docs. |
| docs/source/onnx/moonshine/generate_v2.py | New generator script that renders v2 model docs from the template. |
| docs/source/onnx/moonshine/run.sh | Adds a prebuild entrypoint to run the v2 docs generator. |
| docs/source/onnx/moonshine/generated/v2/.gitignore | Ignores generated v2 .rst outputs in git. |
| docs/source/onnx/moonshine/models-v2.rst | New v2 models index that includes generated per-model pages. |
| docs/source/onnx/moonshine/models.rst | Adds a note clarifying this page is for v1 + links to v2 models. |
| docs/source/onnx/moonshine/index.rst | Adds models-v2.rst and rust.rst to the Moonshine toctree. |
| docs/source/onnx/moonshine/huggingface-space.rst | Splits Hugging Face Space instructions for v1 vs v2 usage. |
| docs/source/onnx/moonshine/rust.rst | New Rust v2 example links page. |
| docs/source/onnx/moonshine/swift.rst | Adds Swift v2 example link. |
| docs/source/onnx/moonshine/python.rst | Adds Python v2 example link. |
| docs/source/onnx/moonshine/pascal.rst | Adds Pascal v2 example link. |
| docs/source/onnx/moonshine/kotlin.rst | Adds Kotlin v2 example link. |
| docs/source/onnx/moonshine/javascript.rst | Adds Node.js + node-addon v2 example links. |
| docs/source/onnx/moonshine/java.rst | Adds Java v2 example link. |
| docs/source/onnx/moonshine/go.rst | Adds Go v2 example links and reformats as lists. |
| docs/source/onnx/moonshine/dart.rst | Fixes Moonshine link + adds Dart v2 example link. |
| docs/source/onnx/moonshine/csharp.rst | Adds C# v2 example links and reformats as lists. |
| docs/source/onnx/moonshine/c.rst | Adds C/C++ v2 example links and reformats as lists. |
| docs/source/onnx/moonshine/code/base-ar.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-en.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-es.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-ja.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-uk.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-vi.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/base-zh.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/tiny-en.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/tiny-ja.txt | Adds captured decode output used by v2 model docs. |
| docs/source/onnx/moonshine/code/tiny-ko.txt | Adds captured decode output used by v2 model docs. |
| docs/Makefile | Runs Moonshine docs generation during make html prebuild. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_asr.kt>`_ | ||
| `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_moonshine_asr_v2.kt>`_ |
There was a problem hiding this comment.
These two links are rendered as two separate paragraphs rather than a list, unlike other language pages updated in this PR. Use a bullet list ("- ...") or otherwise format them consistently so both links display correctly.
| `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_asr.kt>`_ | |
| `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_moonshine_asr_v2.kt>`_ | |
| - `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_asr.kt>`_ | |
| - `<https://github.com/k2-fsa/sherpa-onnx/blob/master/kotlin-api-examples/test_offline_moonshine_asr_v2.kt>`_ |
| Real-time/streaming speech recognition on Android | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Pease visit `<https://k2-fsa.github.io/sherpa/onnx/android/apk.html>`_ |
There was a problem hiding this comment.
Typo: "Pease visit" should be "Please visit".
| Pease visit `<https://k2-fsa.github.io/sherpa/onnx/android/apk.html>`_ | |
| Please visit `<https://k2-fsa.github.io/sherpa/onnx/android/apk.html>`_ |
| "ko": "Korea", | ||
| "ja": "Japanese", | ||
| "en": "English", | ||
| "zh": "Chinese", | ||
| "vi": "Vietnamese", | ||
| "uk": "Ukrainian", | ||
| "ja": "Japanese", |
There was a problem hiding this comment.
The language name for "ko" is set to "Korea" (a country) and the dict contains a duplicated "ja" key. This will render incorrect language names in the generated docs; use "Korean" for ko and remove the duplicate entry.
| "ko": "Korea", | |
| "ja": "Japanese", | |
| "en": "English", | |
| "zh": "Chinese", | |
| "vi": "Vietnamese", | |
| "uk": "Ukrainian", | |
| "ja": "Japanese", | |
| "ko": "Korean", | |
| "ja": "Japanese", | |
| "en": "English", | |
| "zh": "Chinese", | |
| "vi": "Vietnamese", | |
| "uk": "Ukrainian", |
| with open(f"./code/{m}.txt") as f: | ||
| decode_out = f.read() | ||
|
|
||
| output = template.render( | ||
| model_name=get_name(m), | ||
| lang=get_lang(m), | ||
| url=get_url(m), | ||
| apk_name=get_apk_name(m), | ||
| m=m, | ||
| decode_out=decode_out, | ||
| ) |
There was a problem hiding this comment.
decode_out is read from ./code/{m}.txt and passed into the template render, but the template uses literalinclude and never references decode_out. This is dead code; either remove the read/render parameter, or update the template to use the variable.
| .. _moonsine-models-v1: | ||
|
|
||
| Models | ||
| ====== | ||
|
|
||
| .. note:: | ||
|
|
||
| This page is for Moonshine v1, which supports only English. | ||
|
|
||
| Please see :ref:`moonsine-models-v2` for models supporting | ||
| Arabic, Chinese, English, Japanese, Korean, Spanish, Ukrainian, and Vietnamese. |
There was a problem hiding this comment.
The section labels use "moonsine" (missing "h") in both the anchor and the cross-reference. While the ref resolves internally, the misspelling makes external linking/error search confusing; consider renaming to "moonshine-models-v1" / "moonshine-models-v2" and updating the :ref: accordingly.
| for m in models: | ||
| env = Environment(loader=FileSystemLoader(".")) | ||
| template = env.get_template(f"./tpl/model_v2.rst") |
There was a problem hiding this comment.
Environment(...) and get_template(...) are recreated on every iteration of the model loop, which is unnecessary and makes the script harder to modify. Create the Jinja environment/template once before the loop and reuse it.
| for m in models: | |
| env = Environment(loader=FileSystemLoader(".")) | |
| template = env.get_template(f"./tpl/model_v2.rst") | |
| env = Environment(loader=FileSystemLoader(".")) | |
| template = env.get_template("./tpl/model_v2.rst") | |
| for m in models: |
| for m in models: | ||
| env = Environment(loader=FileSystemLoader(".")) | ||
| template = env.get_template(f"./tpl/model_v2.rst") | ||
| with open(f"./code/{m}.txt") as f: |
There was a problem hiding this comment.
The file ./code/{m}.txt contains non-ASCII text (e.g., Korean/Japanese), but it's opened without an explicit encoding. To avoid platform-dependent failures (notably on Windows), open it with encoding="utf-8".
| with open(f"./code/{m}.txt") as f: | |
| with open(f"./code/{m}.txt", encoding="utf-8") as f: |
| .. _moonsine-models-v2: | ||
|
|
||
| Models v2 | ||
| ======== |
There was a problem hiding this comment.
The underline for the title "Models v2" is shorter than the title text (8 '=' vs 9 chars). In reStructuredText, the underline must be at least as long as the title, otherwise Sphinx/docutils may emit warnings or mis-parse the section.
| ======== | |
| ========= |
| @@ -0,0 +1,16 @@ | |||
| .. _moonsine-models-v2: | |||
There was a problem hiding this comment.
The anchor label is spelled "moonsine" (missing "h"). If you rename v1 to "moonshine-models-v1" as well, please keep v2 consistent (e.g., "moonshine-models-v2").
| .. _moonsine-models-v2: | |
| .. _moonshine-models-v2: |
Summary by CodeRabbit
Documentation
Chores