First (failed) attempt at using rustdoc

#1

I have a lib crate that also has one bin.
I created src/doc.rs which contains a single /*! ... */ comment describing the crate and added mod doc; to src/lib.rs.
Then I ran rustdoc -h. This says rustdoc [options] <input> and then explains all the options: but does not say what <input> should be.
Next I ran rustdoc src/lib.rs and that produced an error:

error: environment variable `CARGO_PKG_VERSION` not defined
  --> src/plan/mod.rs:28:32
   |
28 |                                env!("CARGO_PKG_VERSION"));
   |                                ^^^^^^^^^^^^^^^^^^^^^^^^^

I did look at the manual (which is where I realised I had to pass src/lib.rs), but didn’t find a solution.

#2

Why not use cargo docs instead ?
Cargo will manage the different variables needed to invoke rustdoc correctly, and generate doumentation automatically in your crate’s target/doc directory.

1 Like
#3

Try setting the CARGO_PKG_VERSION environment variable. I imagine it should be the version number of your crate. You can set it like this:

CARGO_PKG_VERSION=0.1.0 rustdoc src/lib.rs

Or in a separate command:

export CARGO_PKG_VERSION=0.1.0
rustdoc src/lib.rs
#4

I did try cargo docs but it generates docs for all the crates used by my crate: I just want the docs for just my crate.

Also, I want to use many of the rustdoc command line options none of which seem to be offered by cargo doc, e.g., to add HTML headers etc.

[edit] I finally realised that doing cargo docs generates the docs for my crate plus placeholder redirects for all the other docs. But considering that my docs currently consist of one line of documentation and 4 structs and < 20 methods, the output weighs in at ~200MB!

#5

I tried that & it got rid of the original error. But it then produced lots of compilation errors. Why it is trying to compile I don’t know since I just want it to produce docs.

I would have expected running rustdoc on its own with no args in a directory containing Cargo.toml and a src directory would mean that rustdoc would “do the right thing”, but it seems not.

#6

cargo doc --no-deps

You can customize the rustdoc invocation with cargo rustdoc. cargo rustdoc is to cargo doc what cargo rustc is to cargo build.

#7

rustdoc knows nothing about cargo. As is clearly indicated in the name, the environment variable you’re checking is coming from cargo.

#8

If your code doesn’t compile, then it isn’t valid rust code. Why do you expect it to be able to create docs from invalid rust code?

The Cargo.toml file is a file used by cargo and rustdoc doesn’t know anything about cargo. When you run cargo doc, it is the responsibility of cargo to call rustdoc with the correct environment variables and arguments.

If you want something that “does the right thing” then that is cargo doc.

#9

To be fair, both of these statements are not entirely self-evident. Newcomers don’t have a precise understanding of the interaction of different ecosystem tools, and plenty of env. vars originate at some point with a defined meaning and are later also used by other tools, while not changing the name for compatibility.

#10

It was the --no-deps option that I needed. Now it just documents my crate and the total is just 1.4MB.

Thanks.