rust-lang / rust-lang/docs.rs

Separate root path for invocation-specific JS

Open
#1,851 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug E-medium P-low
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):

  1. Release version 1.0.0 of crate_foo.
  2. Visit https://docs.rs/crate_foo/latest/crate_foo/ and leave it open in a browser tab.
  3. Wait for the next nightly release.
  4. Release version 1.0.1 of crate_foo (and wait for docs to build).
  5. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.