search

rust-lang / docs.rs

crates.io documentation generator
https://docs.rs
MIT License
977 stars 195 forks source link

Custom CSS from `--extend-css` doesn't work #2524

Closed hedgecrw closed 3 months ago

hedgecrw commented 3 months ago

I have a Rust repo at https://github.com/hedgetechllc/musicxml that contains a Rust workspace and 3 sub-projects. To build the docs for the main project (musicxml) to include the contents of a custom CSS file at musicxml/assets/docs.css, I can either run from either the root workspace directory or the musicxml directory:

RUSTDOCFLAGS="--extend-css musicxml/assets/docs.css" cargo doc --no-deps

And everything works fine.

I added the following to the Cargo.toml file in the musicxml directory so that docs.rs would pass the appropriate RUSTDOCFLAGS when building:

[package.metadata.docs.rs]
rustdoc-args = ["--extend-css", "musicxml/assets/docs.css"]

However, this resulted in a build error on docs.rs about musicxml/assets/docs.css not existing. I figured this was probably because the full workspace wasn't being passed to docs.rs and just the musicxml project itself, so I updated the Cargo.toml file to read:

[package.metadata.docs.rs]
rustdoc-args = ["--extend-css", "assets/docs.css"]

...and this caused the docs to build without problem on docs.rs; however, the CSS changes still weren't showing in the docs, and upon inspecting the source code, I can see that the CSS stylesheet is being added as:

<link rel="stylesheet" href="../theme-20240617-1.81.0-nightly-59e2c01c2.css">

...referencing a parent directory .. that doesn't seem to exist on docs.rs. Is this a bug, or am I somehow using the wrong --extend-css flag to get this CSS file to populate correctly. I do a similar manual process on GitHub, and the docs generate just fine there. Thanks!

syphar commented 3 months ago

Thank you for the report! I will need to do some more digging, but my hunch is that this is really a bug. The file seems to be generated, only docs.rs doesn't correctly serve it.

I'll try your build locally with a fix and see if it works then.

syphar commented 3 months ago

fixed in https://github.com/rust-lang/docs.rs/pull/2525