cargo doc --open should start a web server to avoid restrictions with file-based browsing

[kbdluv]

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!

[steveklabnik]

This has historically been controversial. I'm pro, but there are a lot of people against.

[kbdluv]

What are the con arguments?

[est31]

I've just installed Vimium on Firefox, it works great. So maybe install Firefox :).

[chabapok]

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

[est31]

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.

[qmx]

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.

[pravic]

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.

[wez]

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.

[qmx]

I'm hacking together a cargo docserver for this, hopefully it gets somewhere 🙏

[qmx]

just pushed https://crates.io/crates/cargo-docserver, hopefully that's useful for someone besides me

[wez]

@qmx it works, thanks!

[xypnox]

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.

[xypnox]

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.

[frehberg]

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.

[LechintanTudor]

This change would be very useful to me as I run Firefox in a Flatpak container which only has access to ~/Downloads.

[Jaffa-Cakes]

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.

[peterramaldes]

Yea, I tried use here too with python3 -m http.server and no success :(

[SteveLauC]

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?

[SamB]

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.)