rust-lang / rust-lang/cargo

`cargo doc` in workspaces includes removed crates' documentation if their previously built documentation is still in `target/doc`

Open
#6,783 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Problem
Building documentation for a workspace, removing a crate from that workspace, and building documentation again keeps documentation for that removed crate accessible in the sidebar and search index.

Steps
I have a repository to reproduce this at https://github.com/robojumper/cargo-doc-workspace-issue.

PowerShell console transcript:
PS D:\Rust> cargo --version
cargo 1.35.0-nightly (0e35bd8af 2019-03-13)
PS D:\Rust> rustc --version
rustc 1.35.0-nightly (0576ac109 2019-03-24)
PS D:\Rust> git clone https://github.com/robojumper/cargo-doc-workspace-issue.git
Cloning into 'cargo-doc-workspace-issue'...
remote: Enumerating objects: 17, done.
remote: Counting objects: 100% (17/17), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 17 (delta 1), reused 17 (delta 1), pack-reused 0
Unpacking objects: 100% (17/17), done.
PS D:\Rust> cd .\cargo-doc-workspace-issue\
PS D:\Rust\cargo-doc-workspace-issue> git checkout 26190d
Note: checking out '26190d'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b <new-branch-name>

HEAD is now at 26190dc... Initial Commit
PS D:\Rust\cargo-doc-workspace-issue> tree /F
Auflistung der Ordnerpfade für Volume DATA
Volumeseriennummer : 9EE8-64D7
D:.
│   .gitignore
│   Cargo.toml
│
├───liba
│   │   Cargo.toml
│   │
│   └───src
│           lib.rs
│
├───libb
│   │   Cargo.toml
│   │
│   └───src
│           lib.rs
│
└───src
        lib.rs

PS D:\Rust\cargo-doc-workspace-issue> cargo doc --all --no-deps
 Documenting liba v0.1.0 (D:\Rust\cargo-doc-workspace-issue\liba)
 Documenting libb v0.1.0 (D:\Rust\cargo-doc-workspace-issue\libb)
    Finished dev [unoptimized + debuginfo] target(s) in 2.39s
PS D:\Rust\cargo-doc-workspace-issue> git checkout dde0a0
Previous HEAD position was 26190dc... Initial Commit
HEAD is now at dde0a01... Remove libb
PS D:\Rust\cargo-doc-workspace-issue> cargo doc --all --no-deps
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
PS D:\Rust\cargo-doc-workspace-issue> tree /F
Auflistung der Ordnerpfade für Volume DATA
Volumeseriennummer : 9EE8-64D7
D:.
│   .gitignore
│   Cargo.lock
│   Cargo.toml
│
├───liba
│   │   Cargo.toml
│   │
│   └───src
│           lib.rs
│
└───target
    │   .rustc_info.json
    │
    ├───debug
    │   │   .cargo-lock
    │   │
    │   ├───.fingerprint
    │   │   ├───liba-41cbe19eb88fc838
    │   │   │       doc-lib-liba-41cbe19eb88fc838
    │   │   │       doc-lib-liba-41cbe19eb88fc838.json
    │   │   │
    │   │   └───libb-c20586c9d60cc169
    │   │           doc-lib-libb-c20586c9d60cc169
    │   │           doc-lib-libb-c20586c9d60cc169.json
    │   │
    │   ├───build
    │   ├───deps
    │   ├───examples
    │   ├───incremental
    └───doc
        │   .lock
        │   aliases.js
        │   brush.svg
        │   COPYRIGHT.txt
        │   dark.css
        │   favicon.ico
        │   FiraSans-LICENSE.txt
        │   FiraSans-Medium.woff
        │   FiraSans-Regular.woff
        │   LICENSE-APACHE.txt
        │   LICENSE-MIT.txt
        │   light.css
        │   main.js
        │   normalize.css
        │   noscript.css
        │   rust-logo.png
        │   rustdoc.css
        │   search-index.js
        │   settings.css
        │   settings.html
        │   settings.js
        │   source-files.js
        │   source-script.js
        │   SourceCodePro-LICENSE.txt
        │   SourceCodePro-Regular.woff
        │   SourceCodePro-Semibold.woff
        │   SourceSerifPro-Bold.ttf.woff
        │   SourceSerifPro-It.ttf.woff
        │   SourceSerifPro-LICENSE.txt
        │   SourceSerifPro-Regular.ttf.woff
        │   storage.js
        │   theme.js
        │   wheel.svg
        │
        ├───implementors
        │   └───core
        │       └───marker
        │               trait.Send.js
        │               trait.Sync.js
        │
        ├───liba
        │       all.html
        │       index.html
        │       sidebar-items.js
        │       struct.StructA.html
        │
        ├───libb
        │       all.html
        │       index.html
        │       sidebar-items.js
        │       struct.StructB.html
        │
        └───src
            ├───liba
            │       lib.rs.html
            │
            └───libb
                    lib.rs.html

Expected behavior
Opening target/doc/liba/index.html shows only items from liba in the sidebar and search index.

Actual behavior
Opening target/doc/liba/index.html shows liba, libb in the sidebar; libb and libb::StructB are still in the search index and have doc pages.

Notes
I haven't made any changes to liba after removing libb, but even with changes to liba, its pages still reference libb the same way.

This popped up in the master docs for rust-analyzer -- ra_ide_api_light has been removed yet is accessible through all other doc pages and the search index. EDIT: Looks like matklad cleared the Travis cache, so that's a workaround (as is the equivalent cargo clean).

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

Reproduce the issue in the linked cargo-doc-workspace-issue repository by running cargo doc --all --no-deps before and after removing libb. Inspect how Cargo rebuilds target/doc, especially the generated liba and libb pages, sidebar-items.js, and search-index.js. Done means the removed crate no longer has doc pages or appears in liba's sidebar or search index.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.