Skip to content

Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options #152902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GuillaumeGomez wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options #152902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions src/doc/rustdoc/src/command-line-arguments.md
View file
Open in desktop
Copy link
Copy Markdown
Member

@weihanglo weihanglo Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While mergeable info arguments standalone is great, it won't be that useful until we have --emit stabllilized I guess?

See rust-lang/cargo#16167 (comment)

Original file line number Diff line number Diff line change
Expand Up @@ -453,6 +453,35 @@ command line options from it. These options are one per line; a blank line indic
an empty option. The file can use Unix or Windows style line endings, and must be
encoded as UTF-8.

## `--merge`, `--parts-out-dir` and `--include-parts-dir`: control how rustdoc handles files that combine data from multiple crates

By default, they act like `--merge=shared` is set, and `--parts-out-dir` and `--include-parts-dir`
are turned off. The `--merge=shared` mode causes rustdoc to load the existing data in the out-dir,
Copy link
Copy Markdown
Contributor

@notriddle notriddle May 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, we aren’t committing to a particular layout. Just that rustdoc handles them automatically.

We currently go to some effort to “decompile” the output JSON to read it back in, but we don’t have to do it that way. We could drop a .cci folder into the out-dir and read the new-style JSON from there.

View changes since the review

combine the new crate data into it, and write the result. This is very easy to use in scripts that
manually invoke rustdoc, but it's also slow, because it performs O(crates) work on
every crate, meaning it performs O(crates<sup>2</sup>) work.

```console
$ rustdoc crate1.rs --out-dir=doc
$ cat doc/search.index/crateNames/*
rd_("fcrate1")
$ rustdoc crate2.rs --out-dir=doc
$ cat doc/search.index/crateNames/*
rd_("fcrate1fcrate2")
```

To delay shared-data merging until the end of a build, so that you only have to perform O(crates)
work, use `--merge=none` on every crate except the last one, which will use `--merge=finalize`.

```console
$ rustdoc +nightly crate1.rs --merge=none --parts-out-dir=crate1.d -Zunstable-options
$ cat doc/search.index/crateNames/*
cat: 'doc/search.index/crateNames/*': No such file or directory
$ rustdoc +nightly crate2.rs --merge=finalize --include-parts-dir=crate1.d -Zunstable-options
$ cat doc/search.index/crateNames/*
rd_("fcrate1fcrate2")
```
Comment on lines +476 to +483
Copy link
Copy Markdown
Member

@camelid camelid Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be helpful to adjust the example to have another dependency crate too so we can show passing --include-parts-dir multiple times at once.


## `--passes`: add more rustdoc passes

This flag is **deprecated**.
Expand Down
31 changes: 0 additions & 31 deletions src/doc/rustdoc/src/unstable-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,37 +197,6 @@ themselves marked as unstable. To use any of these options, pass `-Z unstable-op
the flag in question to Rustdoc on the command-line. To do this from Cargo, you can either use the
`RUSTDOCFLAGS` environment variable or the `cargo rustdoc` command.

### `--merge`, `--parts-out-dir`, and `--include-parts-dir`

These options control how rustdoc handles files that combine data from multiple crates.

By default, they act like `--merge=shared` is set, and `--parts-out-dir` and `--include-parts-dir`
are turned off. The `--merge=shared` mode causes rustdoc to load the existing data in the out-dir,
combine the new crate data into it, and write the result. This is very easy to use in scripts that
manually invoke rustdoc, but it's also slow, because it performs O(crates) work on
every crate, meaning it performs O(crates<sup>2</sup>) work.

```console
$ rustdoc crate1.rs --out-dir=doc
$ cat doc/search.index/crateNames/*
rd_("fcrate1")
$ rustdoc crate2.rs --out-dir=doc
$ cat doc/search.index/crateNames/*
rd_("fcrate1fcrate2")
```

To delay shared-data merging until the end of a build, so that you only have to perform O(crates)
work, use `--merge=none` on every crate except the last one, which will use `--merge=finalize`.

```console
$ rustdoc +nightly crate1.rs --merge=none --parts-out-dir=crate1.d -Zunstable-options
$ cat doc/search.index/crateNames/*
cat: 'doc/search.index/crateNames/*': No such file or directory
$ rustdoc +nightly crate2.rs --merge=finalize --include-parts-dir=crate1.d -Zunstable-options
$ cat doc/search.index/crateNames/*
rd_("fcrate1fcrate2")
```

### `--document-hidden-items`: Show items that are `#[doc(hidden)]`
<span id="document-hidden-items"></span>

Expand Down
54 changes: 27 additions & 27 deletions src/librustdoc/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -599,33 +599,6 @@ fn opts() -> Vec<RustcOptGroup> {
"",
"path to function call information (for displaying examples in the documentation)",
),
opt(
Unstable,
Opt,
"",
"merge",
"Controls how rustdoc handles files from previously documented crates in the doc root\n\
none = Do not write cross-crate information to the --out-dir\n\
shared = Append current crate's info to files found in the --out-dir\n\
finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files",
"none|shared|finalize",
),
opt(
Unstable,
Opt,
"",
"parts-out-dir",
"Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none",
"path/to/doc.parts/<crate-name>",
),
opt(
Unstable,
Multi,
"",
"include-parts-dir",
"Includes trait implementations and other crate info from provided path. Only use with --merge=finalize",
"path/to/doc.parts/<crate-name>",
),
opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""),
opt(
Unstable,
Expand Down Expand Up @@ -692,6 +665,33 @@ fn opts() -> Vec<RustcOptGroup> {
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
"[rust]",
),
opt(
Stable,
Opt,
"",
"merge",
"Controls how rustdoc handles files from previously documented crates in the doc root\n\
none = Do not write cross-crate information to the --out-dir\n\
shared = Append current crate's info to files found in the --out-dir\n\
finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files",
"none|shared|finalize",
),
opt(
Stable,
Opt,
"",
"parts-out-dir",
"Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none",
"path/to/doc.parts/<crate-name>",
),
opt(
Stable,
Multi,
"",
"include-parts-dir",
"Includes trait implementations and other crate info from provided path. Only use with --merge=finalize",
"path/to/doc.parts/<crate-name>",
),
]
}

Expand Down
34 changes: 17 additions & 17 deletions tests/run-make/rustdoc-default-output/output-default.stdout
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,23 +173,6 @@ Options:
--scrape-tests Include test code when scraping examples
--with-examples path to function call information (for displaying examples in the documentation)

--merge none|shared|finalize
Controls how rustdoc handles files from previously
documented crates in the doc root
none = Do not write cross-crate information to the
--out-dir
shared = Append current crate's info to files found in
the --out-dir
finalize = Write current crate's info and
--include-parts-dir info to the --out-dir, overwriting
conflicting files
--parts-out-dir path/to/doc.parts/<crate-name>
Writes trait implementations and other info for the
current crate to provided path. Only use with
--merge=none
--include-parts-dir path/to/doc.parts/<crate-name>
Includes trait implementations and other crate info
from provided path. Only use with --merge=finalize
--html-no-source
Disable HTML source code pages generation
--doctest-build-arg ARG
Expand Down Expand Up @@ -219,6 +202,23 @@ Options:
removed, see issue #44136
<https://github.com/rust-lang/rust/issues/44136> for
more information
--merge none|shared|finalize
Controls how rustdoc handles files from previously
documented crates in the doc root
none = Do not write cross-crate information to the
--out-dir
shared = Append current crate's info to files found in
the --out-dir
finalize = Write current crate's info and
--include-parts-dir info to the --out-dir, overwriting
conflicting files
--parts-out-dir path/to/doc.parts/<crate-name>
Writes trait implementations and other info for the
current crate to provided path. Only use with
--merge=none
--include-parts-dir path/to/doc.parts/<crate-name>
Includes trait implementations and other crate info
from provided path. Only use with --merge=finalize

@path Read newline separated options from `path`

Expand Down
Loading