From a022647b7aa099a79977037dfa4764e9f17095bb Mon Sep 17 00:00:00 2001
From: Tim Paine <3105306+timkpaine@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:23:41 -0400
Subject: [PATCH 1/2] Parse Rust doc comments as markdown

Rust doc comments are markdown by convention, but sphinxcontrib-rust
defaults to reStructuredText. That left headings such as # Arguments and
# Returns rendering as page headings and fenced code blocks collapsing into
literal backticked text.
---
 docs/src/configuration.md | 8 ++++----
 yardang/build.py          | 3 ++-
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/src/configuration.md b/docs/src/configuration.md
index bc0e33f5..6ed2c273 100644
--- a/docs/src/configuration.md
+++ b/docs/src/configuration.md
@@ -766,7 +766,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 +775,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 +823,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:
diff --git a/yardang/build.py b/yardang/build.py
index b9fd2807..390f9c84 100644
--- a/yardang/build.py
+++ b/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",

From 99009c9e03a37a9b58cca1ad1fa3f84e97d7e0ae Mon Sep 17 00:00:00 2001
From: Tim Paine <3105306+timkpaine@users.noreply.github.com>
Date: Tue, 8 Sep 2026 10:16:46 -0400
Subject: [PATCH 2/2] Install sphinx-rustdocgen explicitly in CI

sphinxcontrib-rust shells out to a sphinx-rustdocgen binary that its Python
package only produces as a side effect of compiling the sdist. When uv
serves a cached wheel that step never runs, the binary is absent, and the
docs build fails resolving the executable.

Main only passes today because its cache was cold, so install the binary
directly rather than depending on a cache miss.
---
 .github/workflows/build.yaml | 5 +++++
 .github/workflows/docs.yaml  | 5 +++++
 docs/src/configuration.md    | 8 +++++++-
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index 347d0444..6c7e8d0c 100644
--- a/.github/workflows/build.yaml
+++ b/.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
 
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 64d3434e..9921cb81 100644
--- a/.github/workflows/docs.yaml
+++ b/.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
 
diff --git a/docs/src/configuration.md b/docs/src/configuration.md
index 6ed2c273..f6c5c4fe 100644
--- a/docs/src/configuration.md
+++ b/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]`.