Separate root path for invocation-specific JS
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.2k
- Forks
- 232
- Avg merge
- 11h 35m
- Merged PRs (30d)
- 60
Description
This is really a cross-team issue for rustdoc and docs-rs, but I figure this is the better repo to discuss on. /cc @rust-lang/rustdoc
Steps to reproduce (hypothetical, haven't manually tested):
- Release version 1.0.0 of
crate_foo. - Visit
https://docs.rs/crate_foo/latest/crate_foo/and leave it open in a browser tab. - Wait for the next nightly release.
- Release version 1.0.1 of
crate_foo(and wait for docs to build). - In that browser tab, click the search box and search for an item.
I believe this will fail to load the search, because the HTML that was sitting in that browser tab expected to load, e.g. https://docs.rs/crate_foo/latest/search-index-20220918-1.66.0-nightly-a37499ae6.js, but that URL no long exists; in its place is something like https://docs.rs/crate_foo/latest/search-index-20220919-1.66.0-nightly-712a6c5a.js (that is, the search index for version 1.0.1, generated by the next day's nightly).
I think this could be fixed by loading all invocation-specific JS from an explicitly versioned URL, even when the HTML is loaded from a /latest/ URL. For instance, if the search index was loaded from https://docs.rs/crate_foo/1.0.0/search-index-20220918-1.66.0-nightly-a37499ae6.js, this would continue to work even when a browser tab is held open across releases.
This would necessitate a new rustdoc flag, by analogy with --static-root-path, maybe --invocation-specific-js-root-path. docs.rs would pass this flag with a URL that points to the explicitly versioned URL for the crate being built.
We could also decide the problem isn't worth fixing. I think this is only a real problem for the search index. The other invocation-specific files (sidebar-items, crates, trait implementors) are loaded on page load so they're not an issue. And presumably a user faced with a broken search bar would simply reload.
However, note that this would also solve #1593. Or, we could solve #1593 (but not this issue) by amending the resource suffix for invocation-specific files to also include the crate version.
Related to #1552.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing rustdoc's --static-root-path handling and the docs.rs build invocation described in the issue. Trace how invocation-specific JavaScript URLs are generated and passed between rustdoc and docs.rs. Done means a versioned root can be supplied so search-index JavaScript loaded from /latest/ remains available across crate releases, with the relevant behavior covered by tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100