rust-lang / rust-lang/cargo

cargo doc should delete search-index.js before invoking rustdoc

Open
#15,499 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-feature-request Command-doc S-needs-design
Dominant language
Rust
Stars
15.5k
Forks
3k
Avg merge
23h 30m
Merged PRs (30d)
51

Description

Problem

Unlike the vast majority of build artifacts, search-index.js is both read and written by rustdoc, in order to append to it in a structured way.

This has the unfortunate side effect of persisting some state across cargo doc runs, as rustdoc will be able to see the output of the previous invocation.

This cannot be easily addressed within rustdoc, as it has no way to tell the difference between two invocations of rustdoc within one larger cargo doc invocation, and two different invocations of rustdoc across two different cargo doc invocations.

The weird read+write behavior of rustdoc is required because it does not have any equivalent to the "linking" step that rustc does, in which it can do one-time finalization and collection.

see https://github.com/rust-lang/rust/issues/140698 and https://github.com/rust-lang/rust/issues/133544 for some of the issues this causes

Proposed Solution

target/doc/search-index.js should be deleted by cargo doc before doing a full documentation rebuild (such as when the command-line arguments have changed, like in --document-private-items).

Notes

I believe crates.js also has a similar behavior.

Contributor guide

Open the contributing guide

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 tracing Cargo's cargo doc full-documentation-rebuild path and how it handles target/doc/search-index.js before invoking rustdoc. Check the related crates.js behavior as well; done means stale search-index state is removed before a full rebuild without disrupting multiple rustdoc invocations within one run.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.