Add sphinx-rust support

Author: timkpaine

.github/workflows/build.yaml

@@ -39,6 +39,9 @@ jobs:
       with:
         version: ${{ matrix.python-version }}
 
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@stable
+
     - name: Install doxygen
       run: sudo apt-get install -y doxygen
 

.github/workflows/docs.yaml

@@ -12,6 +12,9 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
       - name: Install doxygen
         run: sudo apt-get install -y doxygen
 

docs/src/api.md

@@ -40,6 +40,13 @@ Use `doxygenindex` to document all symbols from Doxygen XML:
 ```doxygenindex
 ```
 
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+/examples/cpp/docs/api
+```
+
 ### Document Individual Classes
 
 Or document specific classes with `doxygenclass`:
@@ -60,22 +67,39 @@ This is an example of documenting Rust code using sphinx-rust integration.
 
 Use `rust:crate` to document an entire Rust crate:
 
-```rust:crate calculator
+```{eval-rst}
+.. rust:crate:: calculator
+
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+/api/crates/calculator/index
 ```
 
 ### Document Individual Items
 
 Or document specific structs, enums, and functions:
 
-```rust:struct calculator::Calculator
+```{eval-rst}
+.. rust:struct:: calculator::Calculator
+
 ```
 
-```rust:struct calculator::ScientificCalculator
+```{eval-rst}
+.. rust:struct:: calculator::ScientificCalculator
+
 ```
 
-```rust:enum calculator::Operation
+```{eval-rst}
+.. rust:enum:: calculator::Operation
+
 ```
 
-```rust:enum calculator::CalculatorError
+```{eval-rst}
+.. rust:enum:: calculator::CalculatorError
+
 ```
 

docs/src/configuration.md

@@ -470,3 +470,95 @@ Then in your documentation files, you can use breathe directives:
 \`\`\`{doxygenfunction} MyNamespace::myFunction
 \`\`\`
 ```
+
+## Sphinx-Rust Integration
+
+Yardang provides integration with [sphinx-rust](https://sphinx-rust.readthedocs.io/) for documenting Rust code. To use this feature, install yardang with the sphinx-rust extra:
+
+```bash
+pip install yardang[sphinx-rust]
+```
+
+All sphinx-rust configuration is under `[tool.yardang.sphinx-rust]`.
+
+### `crates`
+
+A list of paths to Rust crates to document.
+
+```toml
+[tool.yardang.sphinx-rust]
+crates = [
+    "path/to/crate1",
+    "path/to/crate2",
+]
+```
+
+### `doc-formats`
+
+A dictionary mapping crate names to their docstring format. Valid values are `"restructuredtext"` (default) or `"myst-nb"` (for markdown docstrings).
+
+```toml
+[tool.yardang.sphinx-rust]
+doc-formats = { mycrate = "myst-nb" }
+```
+
+**Note:** When using `myst_nb` as your Sphinx parser (which yardang uses by default), use `"myst-nb"` instead of `"markdown"` for markdown docstrings.
+
+### `viewcode`
+
+Enable links to the source code for documented items. Defaults to `true`.
+
+```toml
+[tool.yardang.sphinx-rust]
+viewcode = true
+```
+
+### Complete Example
+
+Here's a complete example configuration for a Rust project:
+
+```toml
+[tool.yardang]
+title = "My Rust Library"
+root = "docs/index.md"
+pages = ["docs/api.md", "docs/examples.md"]
+use-autoapi = false
+
+[tool.yardang.sphinx-rust]
+crates = [
+    "crates/mylib",
+    "crates/mylib-utils",
+]
+doc-formats = { mylib = "myst-nb", "mylib-utils" = "restructuredtext" }
+viewcode = true
+```
+
+Then in your documentation files, you can use sphinx-rust directives:
+
+````markdown
+# API Reference
+
+## Document a Crate
+
+\`\`\`{eval-rst}
+.. rust:crate:: mylib
+
+\`\`\`
+
+## Document Individual Items
+
+\`\`\`{eval-rst}
+.. rust:struct:: mylib::MyStruct
+
+\`\`\`
+
+\`\`\`{eval-rst}
+.. rust:enum:: mylib::MyEnum
+
+\`\`\`
+
+\`\`\`{eval-rst}
+.. rust:function:: mylib::my_function
+
+\`\`\`
+````

pyproject.toml

@@ -195,6 +195,7 @@ projects = { calculator = "examples/cpp/xml" }
 default-project = "calculator"
 
 [tool.yardang.sphinx-rust]
-rust_crates = [
+crates = [
     "examples/rust",
 ]
+doc-formats = { calculator = "myst-nb" }

yardang/build.py

@@ -319,7 +319,6 @@ def customize(args):
                 "toctree",
                 "literalinclude",
                 "include",
-                "eval-rst",
             ],
             "nb_execution_mode": "off",
             "nb_execution_excludepatterns": [],