Parse Rust doc comments as markdown

.github/workflows/build.yaml

@@ -46,6 +46,11 @@ jobs:
       - name: Setup Rust
         uses: actions-ext/rust/setup@0f0b7c9ab3cdb6e9a1f79e2147974d6762ddafea
 
+      # sphinxcontrib-rust shells out to this binary. Installing the Python
+      # package only builds it as a side effect, which a cached wheel skips.
+      - name: Install sphinx-rustdocgen
+        run: cargo install sphinx-rustdocgen --version 1.2.1
+
       - name: Install JSDoc and TypeDoc
         run: npm install -g jsdoc typedoc
 

.github/workflows/docs.yaml

@@ -27,6 +27,11 @@ jobs:
     - name: Setup Rust
       uses: actions-ext/rust/setup@0f0b7c9ab3cdb6e9a1f79e2147974d6762ddafea
 
+    # sphinxcontrib-rust shells out to this binary. Installing the Python
+    # package only builds it as a side effect, which a cached wheel skips.
+    - name: Install sphinx-rustdocgen
+      run: cargo install sphinx-rustdocgen --version 1.2.1
+
     - name: Install JSDoc/TypeDoc
       run: npm install -g jsdoc typedoc
 

docs/src/configuration.md

@@ -751,7 +751,13 @@ Yardang provides integration with [sphinxcontrib-rust](https://gitlab.com/munir0
 pip install yardang[rust]
 ```
 
-This extra is GPL-3.0 licensed, unlike yardang itself, which is Apache-2.0. It also builds a `sphinx-rustdocgen` helper binary on install, so a Rust toolchain must be available.
+This extra is GPL-3.0 licensed, unlike yardang itself, which is Apache-2.0.
+
+It also relies on a `sphinx-rustdocgen` binary, which the Python package only builds as a side effect of compiling its sdist. Installing from a cached wheel skips that step, so install the binary explicitly to be sure it is present:
+
+```bash
+cargo install sphinx-rustdocgen
+```
 
 All configuration is under `[tool.yardang.sphinx-rust]`.
 
@@ -766,7 +772,7 @@ crates = { crate1 = "path/to/crate1", crate2 = "path/to/crate2" }
 
 ### `doc-dir`
 
-Where the generated pages are written, relative to the documentation root. Defaults to `"api"`, producing `api/<crate>/lib.rst` for each crate.
+Where the generated pages are written, relative to the documentation root. Defaults to `"api"`, producing `api/<crate>/lib.md` for each crate.
 
 ```toml
 [tool.yardang.sphinx-rust]
@@ -775,11 +781,11 @@ doc-dir = "api"
 
 ### `rustdoc-fmt`
 
-The markup used inside Rust doc comments, either `"rst"` (default) or `"md"`. Accepts a single value for all crates, or a per-crate mapping.
+The markup used inside Rust doc comments, either `"md"` or `"rst"`. Defaults to `"md"`, since Rust doc comments are conventionally markdown. Accepts a single value for all crates, or a per-crate mapping.
 
 ```toml
 [tool.yardang.sphinx-rust]
-rustdoc-fmt = { mycrate = "md" }
+rustdoc-fmt = { mycrate = "rst" }
 ```
 
 ### `visibility`
@@ -823,7 +829,7 @@ use-autoapi = false
 [tool.yardang.sphinx-rust]
 crates = { mylib = "crates/mylib", mylib-utils = "crates/mylib-utils" }
 doc-dir = "api"
-rustdoc-fmt = { mylib = "md" }
+rustdoc-fmt = { mylib-utils = "rst" }
 ```
 
 The pages are generated for you, so your documentation files only need a toctree entry pointing at them:

yardang/build.py

@@ -463,7 +463,8 @@ def customize(args):
             # sphinxcontrib-rust
             "rust_crates": {},
             "rust_doc_dir": "api",
-            "rust_rustdoc_fmt": "rst",
+            # Rust doc comments are markdown, unlike the extension's own "rst" default
+            "rust_rustdoc_fmt": "md",
             "rust_visibility": "pub",
             "rust_strip_src": True,
             "rust_generate_mode": "changed",