Make it possible to use docs.rs offline for pages that have been visited at least once

[jyn514]

It'd be great to turn docs.rs into an offline-first PWA (Progressive Web App). So the user would still be able to browse the docs they have already visited before even when offline, without having to use a separate website or app.

The same could be done for doc.rust-lang.org.

Originally posted by @teohhanhui in #174 (comment)

[jyn514]

The same could be done for doc.rust-lang.org.

You can open an issue on https://github.com/rust-lang/www.rust-lang.org for that site, it's managed by a different team. I imagine they would be very receptive since it's a completely static site.

Another alternative is a browser extension to redirect online version -> offline version, similar to what the IPFS Companion extension does. For example:
https://doc.rust-lang.org/std/sync/struct.RwLock.html -> file:///home/teohhanhui/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/share/doc/rust/html/std/sync/struct.RwLock.html

Hmm, this is an interesting idea. I don't think it would work with relative links though, .. would send you to doc/rust/html/std/sync/index.html which might not yet exist. Also I'm not sure that this would work correctly if we used trailing slashes on any page instead of /index.html.

That can be achieved with cargo doc to build local crates and rustup doc for the book, std, and everything else on doc.rustlang.org

The whole point of docs.rs is that you don't have to build the docs yourself, so while useful a useful tip I don't think it should replace being able to use docs.rs offline.

I don't know very much about PWAs. If we set pages to be cached for a longer time, would that meet this use case? That way you could visit the cached page even when you lost internet.

[Kixiron]

In regards to relative links, I wouldn't be sad if they went away, as they're not really a great thing in the first place. Replacing relative links would probably help simplify a good portion of code while also being less finicky/more difficult to mess up

[jyn514]

In regards to relative links, I wouldn't be sad if they went away, as they're not really a great thing in the first place. Replacing relative links would probably help simplify a good portion of code while also being less finicky/more difficult to mess up

I strongly disagree. Without relative links we'd have to hardcode https://docs.rs at the start of every url, which would break this anyway.

[jyn514]

Also, rustdoc heavily uses relative links for documentation, I don't see a good way to change that since it doesn't know the absolute URL it will be used with.

[Kixiron]

Oh, I thought you meant relative links in reference to how we do our own source browser, with .. being "up", but it seems we already use a canonical link for that

[teohhanhui]

I don't know very much about PWAs. If we set pages to be cached for a longer time, would that meet this use case? That way you could visit the cached page even when you lost internet.

See https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Offline_Service_workers#Offline_First

Changing the cache expiry would help, however that requires the user to manually toggle offline mode in their browser (which is a very hidden thing nowadays, if not impossible altogether...)

[jyn514]

Changing the cache expiry would help, however that requires the user to manually toggle offline mode in their browser

That seems to defeat the point of caching :(

Glancing through the page you linked it seems like the main idea is to have some JavaScript that checks if the page is cached before making a network request. I agree that should be the behavior, but I'm not comfortable enough with JavaScript to implement it /don't have the time. If someone is interested in working on this I'd be happy to mentor though :) almost all of the site can be cached except the home page, /releases, and redirects.

[wanderrful]

Angular apps have service workers built into them implicitly, so if you guys are willing to upgrade this from a Python Jinja-like Tera front-end (https://crates.io/crates/tera) to an Angular front-end then you can get the Service Worker caching for free.

Here's some more info: https://angular.io/guide/service-worker-intro

As for the rust-lang website itself, it has a Handlebars front-end (https://github.com/rust-lang/www.rust-lang.org/blob/master/templates/index.hbs), which could also be replaced with an Angular front-end.

However, I think it'd probably be more on-brand for these Rust websites to have a Rust-based front-end that compiles to WebAssembly rather than be Javascript-based. The only such Crate I'm aware of that might do this is Yew, but it doesn't have Service Workers built into it as far as I know. It's not "production-ready", but since these websites are just static pages I don't think that that's a concern.

Angular could potentially be overkill since these sites are just static pages, but just because it has a bunch of bells and whistles doesn't mean you have to use them.

[jyn514]

I'd strongly prefer for docs.rs to remain a static site first and foremost, and especially remain usable with JavaScript disabled. I'm fine with JS adding features on top, but the JS shouldn't be necessary just to use the site.

That said I don't know much about frontend, so maybe Angular can do that?