diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md index b55ddf6e0e165..456235c755896 100644 --- a/src/doc/rustdoc/src/command-line-arguments.md +++ b/src/doc/rustdoc/src/command-line-arguments.md @@ -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, +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(crates2) 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") +``` + ## `--passes`: add more rustdoc passes This flag is **deprecated**. diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index ae007c4c13bb5..15e22a34933fa 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -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(crates2) 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)]` diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 541ab3d1c295e..f490a7f7a91af 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -599,33 +599,6 @@ fn opts() -> Vec { "", "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/", - ), - 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/", - ), opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""), opt( Unstable, @@ -692,6 +665,33 @@ fn opts() -> Vec { "removed, see issue #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/", + ), + 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/", + ), ] } diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout index 4e28be347cbb1..c22c08d4e7c2b 100644 --- a/tests/run-make/rustdoc-default-output/output-default.stdout +++ b/tests/run-make/rustdoc-default-output/output-default.stdout @@ -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/ - 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/ - 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 @@ -219,6 +202,23 @@ Options: removed, see issue #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/ + 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/ + Includes trait implementations and other crate info + from provided path. Only use with --merge=finalize @path Read newline separated options from `path`