Documenting and files in examples directory

help
1

I am using

cargo --version
cargo 1.87.0 (99624be96 2025-05-06)

The rust book

suggests using

cargo doc -Zunstable-options -Zrustdoc-scrape-examples

but when I try to do this I get

error: the `-Z` flag is only accepted on the nightly channel of Cargo, but this is the `stable` channel
See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information about Rust release channels.
1 Like
2

The error message is pointing you to the solution. You might be used to error messages not being helpful, but in Rust they usually point you in the right direction.

That being said, you need to use the nightly channel of compiler, so all you need to do is this (assuming you're using rustup and you have installed the nightly channel):

rustup override set nightly

If you haven't installed the nightly release channel, you'll have to do this before running the command above:

rustup toolchain install nightly
3

The suggestion to use this option appeared in a 2022 discussion

Does this mean that the option is still unstable and will probably not become a normal option ?

4

That seems the case.

I wouldn't go as far. It's probably just that this hasn't received as much love.

1 Like
5

If you are using rustup, you can also use the toolchain override flag: cargo +nightly ... to switch from your default to the nightly toolchain.

Yes.

I don't think so, this one looks to me like it will be stabilised eventually. But stabilisation takes time, effort and feedback from the users, all being scarce sometimes in open source.

6

If I stick with the standard version of rust, how do you suggest I include large examples that:

  1. Can be run as tests to make sure they still work.
  2. Do not have /// at the start of each line.
  3. Will be part of the documentation with supporting text that explains them.
7

You can use multiline doc comment syntax to write doctests without ///:

/*!
Module documentation

```
println!("test 1");
```
*/

/**
Function documentation

```
println!("test 2");
```
*/
pub fn foo() {}
3 Likes
8

If you put the large examples in examples/[1], Cargo will automatically treat them as example targets. You can run them as tests with cargo test --examples or cargo test --all-targets.

You can manually import them with include_str!, e.g.:

/// ```
#[doc = include_str!("../examples/foo.rs")]
/// ```
pub struct Foo;

  1. Or make them otherwise accessible to Cargo via the manifest. ↩︎

2 Likes
9

My mistake was not putting #[test] in examples/add.rs.
Without this run example/add.rs

cargo test --all-targets

...

     Running unittests examples/add.rs (target/debug/examples/add-b99ae23a53871b3f)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
10

Is there some way to only include the part of the file starting at the line after some text and ending at the line before some text; i.e., like the

:start-after: text
:end-before: text¶

in the sphinx literal-include directive; see

11

I think you can get something akin to this with the include-utils crate. It supports importing portions of a file similar to mdbook.

1 Like
12

Perhaps include-utils is only intended to work with markdown files ?

I created a hello_world project using

cargo new hello_world

I then changed the Cargo.toml dependencies to

[dependencies]
include-utils = "0.2.4"

and changed main.rs to

use include_utils;

/// Hello World
/// '''
#[doc = include_utils::include_md!("src/main.rs:main")]
/// '''
///
// ANCHOR: main
fn main() {
    println!("Hello, world!");
}
// ANCHOR_END: main
~

I then ran cargo doc and got the following error:

 hello_world>cargo doc
 Documenting hello_world v0.1.0 (/Users/bradbell/trash/rust/hello_world)
error: Included file doesn't contain anchor with name: main
 --> src/main.rs:5:9
  |
5 | #[doc = include_utils::include_md!("src/main.rs:main")]
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: this error originates in the macro `include_utils::include_md` (in Nightly builds, run with -Z macro-backtrace for more info)

error: could not document `hello_world`
13

Looks like anchors are not supported for include_str_part!. Raising an issue in the repo might be a good idea, I don't see a reason why this shouldn't be supported. A suitable regex can be found in the mdbook docs:

The line beginning an anchor must match the regex ANCHOR:\s*[\w_-]+ and similarly the ending line must match the regex ANCHOR_END:\s*[\w_-]+. This allows you to put anchors in any kind of commented line.

14

I posted the following issue:

1 Like