Docs.rs local build fails when using `workspace = true`

I Recently had problems with some of my documentations not building on [docs.rs]. Thus I decided to research how to run these builds locally since simply using cargo doc does not yield the same result.
After careful reading of GitHub - rust-lang/docs.rs: crates.io documentation generator, I was able to set up the docker container as described. However, with this setup I cannot compile any workspace members if workspace = true is specified in any of the Cargo.toml files.

MWE

Consider a simple project with one workspace member.
The contents of main.rs and lib.rs are irrelevant at this time.

β”œβ”€β”€ Cargo.toml
β”œβ”€β”€ member
β”‚   β”œβ”€β”€ Cargo.toml
β”‚   └── src
β”‚       └── main.rs
└── src
    └── lib.rs

The upper Cargo.toml file contains settings for the workspace:

[workspace]
members = ["member"]

[workspace.dependencies]
rand = "0.8.5"

[package]
name = "my_lib"
version = "0.1.0"
edition = "2021"

while the second Cargo.toml file defines the member of the workspace:

[package]
name = "member"
version = "0.0.1"
edition = "2021"

[dependencies]
rand = { workspace = true }

I picked the rand crate to showcase my point. If I use the cargo run -- build crate -l path/to/my_lib/member command from GitHub - rust-lang/docs.rs: crates.io documentation generator the build fails.
However, building the docs for the workspace works out fine cargo run -- build crate -l path/to/my_lib. When changing from rand = { workspace = true } to rand = "0.8.5", the build also runs fine for the member crate.

Question

What do I need to do in order to mimick the build done by docs.rs? I have a workspace which uses the workspace = true syntax in multiple places but its buld of the documentation works out fine. How can I achieve that locally as well?

When a package is published, its Cargo.toml is transformed so that, among other things, it no longer contains any workspace inheritance. So, the docs.rs build doesn't need to support workspaces.

You can get the same result locally by running cargo package and then extracting the code (or just the Cargo.toml) from the package file.

1 Like

Thanks so much! This is exactly what I was looking for.

To me it seems that this important step was not documented at all in docs.rs. But I could also not find a detailed guide on how to reproduce exactly the same builds locally as what is being done by docs.rs. Maybe I overlooked something.

It's probably not documented just because workspace inheritance is a new feature in Cargo β€” while older versions of Cargo still transformed the Cargo.toml, the changes were less significant β€” and nobody thought about updating the docs.rs documentation with info about it.

You could contribute an update to the documentation. (I've never done this myself, so I'm not in a good position to describe the actual workflow.)

1 Like

Do you know by any chance why there is not a concise documentation for docs.rs except for really long README.md files? I would expect, that it builds its own documentation with itself. Like a compiler that bootstraps itself. But it does not seem that way.

I think I can provide at least some context here.

Generally, docs.rs’ primary use-case is still the docs.rs platform itself and while we’re trying to keep the self-hosting use-case alive, we currently can’t spend enough time on providing more tooling & documentation for self-hosters.

Currently we have two places of documentation:

  • the README you’re referring to, which is more geared towards developers who want to contribute to docs.rs itself
  • rust-forge / docs.rs docs, which should contain more info generally, and is outdated. ( it’s managed here)

I feel like the better way to document docs.rs for self-hosters (= users of the application) is not rustdoc itself, since it’s not documenting the code itself, but how the application should be used. So IMO the guide-syle docs at rust-forge are a better fit for this.

All of that being said, I would love to help with & review

  • any improvements to the rust-forge docs
  • any improvements to the code docs / the readme
  • any attempts to library-fy docs.rs more to make parts useable in alternative package repositories like kellnr
3 Likes

I can totally understand that this has a higher priority. Thanks for also pointing out the additional resources :+1: I agree that guide-style documentation is what most people will be looking for.

I believe you have already seen my PR in github. I will be happy to provide more details but will only have time to come back to you in a few days.

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.