Many workspace packages do not need manual intervention and can be built simply by executing the commands listed in the main Readme.md file. However, some workspaces require an additional step. This is the case when values such as
version.workspace = trueare inherited from the workspaces Cargo.toml configuration file.
To build documentation, rustdoc requires a fully specified package but rustdoc does not understand workspaces which are only defined in cargo.
Thus our crate needs to be packaged by cargo before running the documentation.
This step will replace all of the value.workspace = true statements with their respective values.
cargo package
This will emit a packaged crate into the target/package/your_crate_name-version folder.
Now the commands specified in Readme.md can be executed targeting this folder.
cargo run -- build crate --local /path/to/source/target/package/your_crate_name-version/
To showcase when such problems can occur, take a look at the following example.
$ tree
.
├── Cargo.toml
├── my_lib
│ ├── Cargo.toml
│ └── src
│ └── lib.rs
└── README.md
3 directories, 4 filesThe actual contents of my_lib do not matter, only the two configuration files.
$ cat Cargo.toml
[workspace]
members = [
"my_lib",
]
[workspace.package]
version = "0.1.0"
and
$ cat my_lib/Cargo.toml
[package]
name = "my_lib"
version.workspace = true
[dependencies]The build command
cargo run -- build crate -l path/to/docs_rs_workspace_package/my_libfails with
Error: Building documentation failed
Caused by:
Building documentation failed
Caused by:
invalid Cargo.toml syntaxwhich makes sense due to
version.workspace = trueHowever when running the following sequence of commands
# Run this in the directory of docs_rs_workspace_package
cargo package -p my_liband then building again
# Run this from the docs.rs repo
cargo run -- build crate -l path/to/docs_rs_workspace_package/target/package/my_lib-0.1.0then the build succeeds.