add information about packaging crate

[jonaspleyer]

This is a minor addition. Usually when working with the build crate -l command, it is enough to apply it directly to the crate root.
However, when using cargo features such as inheritance of workspace settings (ie. version.workspace = true) it is necessary to package the crate first with cargo package.

I am aware that the wording "package" should already make this clear. However, I stumbled across this problem personally and could not figure out the solution. Please correct me if I have overlooked any other documentation where this makes more sense.

[syphar]

Thank you for the improvement! This really helps!

[jonaspleyer]

Hey everyone. Sorry for taking so long. I have created a sample repo which showcases how workspaces packages cannot be build by using the commands as explained in the README.md file.

Example

https://github.com/jonaspleyer/docs_rs_workspace_package

Structure

$ tree
.
├── Cargo.toml
├── my_lib
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
└── README.md

3 directories, 4 files

The 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]

Building

The build command

cargo run -- build crate -l path/to/docs_rs_workspace_package/my_lib

fails with

Error: Building documentation failed

Caused by:
    Building documentation failed

Caused by:
    invalid Cargo.toml syntax

which makes sense due to

version.workspace = true

Fix

However when running the following sequence of commands

# Run this in the directory of docs_rs_workspace_package
cargo package -p my_lib

and 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.0

then the build succeeds.

[jonaspleyer]

@syphar how to we continue from here? This was a lot of information in my previous comment and I am unsure how to include it in the README.md

[GuillaumeGomez]

There is a docs folder. Don't hesitate to add more entries into it.

[jonaspleyer]

I have followed your suggestions. Somehow I feel a bit stressed when writing these things in the /docs folder.
Would it not make sense to take many of the information in the Readme.md and either include this information on docs.rs itself or possibly as a book?

[jonaspleyer]

I have inserted a more detailed description of when this problem occurs and how to circumvent it in the docs folder. I hope that this is sufficiently detailed to give a clear explanation.