cargo
cargo copied to clipboard
rust-lang
`cargo doc --open` should start a web server to avoid restrictions with file-based browsing
Running cargo doc --open currently opens the file in the browser with the file:// protocol.
In this protocol, web extensions like Vimium don't have access to the page and can't provide keyboard shortcuts.
It would be nice if running cargo doc --open would start a web server like http then navigate to the generated index file. I've tested that and Vimium works normally. Thank you!
This has historically been controversial. I'm pro, but there are a lot of people against.
As far as I understand, it's browser or vimium problem.
But if we do this, it makes sense to use separate key, for example: cargo doc --open_with_embedded_webserver
Yeah it is a Chrome bug. In general, Chrome cares only very little about the file:// protocol: https://bugs.chromium.org/p/chromium/issues/detail?id=47416
But why should firefox users being made suffer? Firefox works great, but http://localhost is far more inconvenient than file protocol based services.
having a built-in server would be really useful for those that usually work inside a ssh session/vm and use a browser outside the shell session.
for those that usually work inside a ssh session/vm
Why trying to squash the universe inside one tool? Let cargo doc generate documentation, let another tool host it.
This gist has some one-liners for spinning up a web server for static content: https://gist.github.com/willurd/5720255
eg:
cargo doc && cd target/doc && python3 -m http.server 8000
will spin up an http server on 0.0.0.0:8000 (potentially world accessible; take appropriate care!).
It's not as convenient as cargo doc --open but it's not super terrible.
While I'm on the fence about building this support directly into cargo, it would be nice if there was an easy way to do this, or that the docs/help pushed folks towards a couple of nice recipes to help with this use case.
just pushed https://crates.io/crates/cargo-docserver, hopefully that's useful for someone besides me
Probably if it is an edge case scenario, you can use https://www.npmjs.com/package/serve to serve your docs to a localhost and then open that in chrome(ium).
This is much simpler solution than building a server inside cargo itself.
This has historically been controversial. I'm pro, but there are a lot of people against.
Then why you use a web browser.
Probably if it is an edge case scenario, you can use https://www.npmjs.com/package/serve to serve your docs to a localhost and then open that in chrome(ium).
This is much simpler solution than building a server inside cargo itself.
How can this be simple? You need nodejs to run it. Have you lost your mind?
How can this be simple? You need nodejs to run it. Have you lost your mind?
No I haven't. What I meant with the suggestion was that cargo is not meant to be a server. Including an http server just to view docs on localhost doesn't make much sense when there are libraries such as cargo-docserver.
I was just suggesting a simple solution in terms of the time it would take for someone to use it. Granted it is simple only for those who already have node installed, but it is a simple solution nonetheless.
Web-browser are getting more strict regarding file access. The access/import of files from dynamically created path strings will be blocked when using the file-protocol. Rustdoc's deep hierarchical folder structure (sub-folder per mod) requires dynamic import paths for the generalized helper-scripts in folder "static.files/"
Short Story
My proposal is to use a flattened rustdoc HTML file structure instead, that will permit to reference the helper scripts using static paths always, such as "../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2" (one level up).
Long Story
The rustdoc is organized in folders hierarchically, within each document the relative location of the folder static.files/ is derived reading the following attribute
var rootPath = document
.getElementById('rustdoc-vars')
.attributes['data-root-path']
.value;
Due to this fact the import paths for further scripts/files are constructed dynamically using rootPath as prefix. When using the file-protocol to read the rustdoc, these dynamic imports will be blocked by the browser, see CORS error message of Chrome below.
await import(rootPath + "static-files/....js");
This means, when using the file-protocol certain styles and features can not be loaded form folder static.files and the rustdocs will appear differently compared to using the http-protocol.
Proposal
The solution might be to turn to static import paths. This could be achieved by flattening the folder structure of the rustdocs, using a file set for each crate of folder depth=1 only, so that a static string could be use for the import paths always.
import x from "../static.files/...js";
Using static import paths, the CORS issue would no longer exist and the file-protocol could be used the same way as http-protocol. ( AFAICS)
PS: other rustdocs add-ons such as aquamarine must evaluate rootPath value as well, right now. Using a flattened folder structure (depth=1), the integration of these tools would be simplified.
This change would be very useful to me as I run Firefox in a Flatpak container which only has access to ~/Downloads.
Thought I would add in a real-world use case issue that I'm experiencing and am sure other people are running into these days as well:
For those that use VSCode with Devcontainers, running cargo doc --open does not work as you are inside a container and any of the file locations it opens to cannot be used from the host machine browser. It is possible to go directly to the generated docs directory if you are already on your own computer and open it manually with a mounted volume, but this is not possible at all if you are using Devcontainers in a remote environment.
The solution for this would be an HTTP server that serves the files in a basic manner.
In addition to the above, it looks as though docserver is now dead, being archived as of May 28th, 2022 with the most recent release on March 14th, 2020. I may look into creating an alternative CLI tool to support this, but it would still be nice if there was a basic HTTP server built into the cargo doc command itself.
Yea, I tried use here too with python3 -m http.server and no success :(
just pushed https://crates.io/crates/cargo-docserver, hopefully that's useful for someone besides me
Hi @qmx, may I ask why this repo is archived?
cargo doc --open also doesn't work from Termux on my phone. Termux tries to open some content:// URL in a browser but it doesn't work, and when I attempt to manually open the docs in a browser, Chrome doesn't even seem to recognize file:// URLs, and Firefox appears to treat them as aliases for about:blank. (I was actually expecting to just get a read error because /data/data/com.termux/files/home can't be read by other apps.)
My solution is using --target-dir to put the docs in a location that Chrome is happy with (~/Documents).
just pushed https://crates.io/crates/cargo-docserver, hopefully that's useful for someone besides me
Hi @qmx, may I ask why this repo is archived?
Reason is simple: I stopped maintaining it!
The cargo team briefly discussed this (and I brought it up with the rustdoc team at https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/local.20server/with/522152745 as well). We didn't have any specific blocking concerns other than some minor concerns. Some considerations might be:
- The weight of the dependencies necessary to support this.
- The maintenance burden on the cargo team.
- See https://github.com/rust-lang/mdBook/issues/?q=is%3Aissue%20state%3Aopen%20label%3ACommand-serve for similar burden that happens with mdbook.
- Avoid scope creep.
- Making it clear this should not be used in production.
- Possible coordination with the rustup team for supporting a similar feature for
rustup doc.
Design wise, I've been considering whether we should have interactive modes for our commands which would include include watch support (rebuilding on changes). I wonder if we should tie running a server into that.
Doesn't seem to be in the previous conversation (apologies if I missed it) - when working with a DevContainer or a remote machine, it's not always easy to get access to the files on the host machine after cargo docs have been generated. LOT of files to be downloaded.
cargo doc --open would require just a simple port-forward (available in most remove dev environments) that can allow us to view the docs. Especially useful in macro-filled projects to see if the types are getting generated correctly.
@qmx would you be open to transferring ownership of the crate? Happy to maintain it going forward
This was marked needs-mentor but in the meeting notes and the summary here, this sounds like there are still a lot of open questions around this so I switched to needs-design.
Implementation wise, we have
- https://crates.io/crates/cargo-docserver
- pulling out mdbook's serve logic
- file-serve which I extracted from a SSG I maintain and attempts to stay light weight to build and has "find a free port" mode
It might also be good to survey other tools with a serve functionality, e.g. mdbook and my SSG allow overriding the hostname and port. Is that required for an MVP? Does it need to be on the command-line or could it be in config (which can also be set via env / command-line).