file:// urls for doc incompatible with snap/flatpak/container-based-development

[ahayzen-kdab]

Problem you are trying to solve

There are various issues around confinement and working with containers on Linux where the path of the html docs either ends up wrong or the browser does not have permission to open the html docs.

• a flatpak or snap of firefox cannot open files in /home (it would need to be granted permission)
• if i'm developing inside a container (eg a vscode remote container) the paths rustup produces are incorrect outside the container

Solution you'd like

Provide an option to serve the docs as a port like mdbook serve ( https://rust-lang.github.io/mdBook/cli/serve.html ), maybe like rustup doc --serve

This allows for both confined applications and developing inside a container to then work as they don't need to access the html files via a path, but instead just open localhost:8080 etc.

Notes

This would resolve issues like #3110 #2997 #2988 as there is no issue with confinement on ports.

If this is something this is possible, it would be good for cargo doc --serve to also exist as the same problem occurs with cargo doc --open. And this would then make both rustup and cargo consistent with mdbook serve which has this ability.

[Vaisakhkm2625]

I am only starting rust today (i tried once few month before )and i saw rustup doc --book is not working... This was my exact thought, why it is not served in a port.... https://github.dev/rust-lang/rustup/blob/89f103761e61b87d27070c65aae1f6c4d06c5855/src/cli/rustup_mode.rs#L1593

i guess this the implementation of rustup doc, and this helps anyone who wanted to make this feature...

or may be i will try in the future....

[rbtcollins]

I think a rustup doc serve feature would be nice.

[HarrisonHemstreet]

I am seeing this issue too

[HarrisonHemstreet]

@rbtcollins I would be very happy to take this task on. Any help you would be willing to give / able to give would be highly appreciated :slightly_smiling_face:

[rbtcollins]

The functional requirement is that rustup should be able to spawn a webserver pointing at the docs, as a new feature complementary to spawning a browser on the file:// url it does today.

Theres a lot of room for UX experimentation here:

• does rustup doc automatically spawn a webserver?
• when a webserver is spawned, does rustup return (and the webserver is forked to the background), or does rustup only return when the server is shutdown?
• what happens when multiple rustup servers are requested for the same doc version
• what happens when multple rustup servers are requested for different doc versions?
• does rustup both spawn a server and call xdg-open on the server url ?

I don't know whats right; my hunch is that something like the following would work ok:

• always allocate a random port (by binding to 0)
• webserver runs in foreground, making it visible to users
• default to also doing xdg-open, but allow all three combinations:
  • serve without open
  • serve and open
  • don't serve and open

I think adding a '--serve' option to the existing doc command would be ok, but it probably needs to default off as folk may have doc in scripts etc which would break. We can look at making serving the default as a future change.

[HarrisonHemstreet]

Sounds good! I'll try working on this! :slightly_smiling_face:

[HarrisonHemstreet]

@rustbot claim

[donottellmetonottellyou]

Is this being worked on? I have been using cargo-docs, but it doesn't seem to work on local crates, only the rust book.

[djc]

My impression is that it's not being worked on -- I don't see any related open PRs. @HarrisonHemstreet are you still intending to work on it?

[rbtcollins]

@donottellmetonottellyou rustup doc's scope is only documentation shipped by the rust project itself, not docs for local crates.

[brettearle]

G'day If @HarrisonHemstreet isn't currently working on this?, can I jump on board? I'll just put up a MVP --serve flag and serve it on 0. What's the convention in rust up, just std lib or do we have a web crate we like?

[rbtcollins]

@brettearle we use external crates that are license compatible; we're just about to introduce a pervasive tokio runtime, so I would suggest something async + tokio based.

[brettearle]

G'day, trying to use tokio inside cli/rustup and it's not allowing the import, it's in dependencies in cargo.toml but has flag workspace= true, is there something special to get this use statement to work? Sorry if this is obvious new to production rust

[Audiosutras]

Hello I just stumbled on this issue in Ubuntu as well. Any motion on the serve feature?

[djc]

Nope, it hasn't been a priority for us. If someone wants to help out, that would be great!