rustdoc: add `--print` option by ShE3py · Pull Request #151618 · rust-lang/rust

ShE3py · 2026-01-24T21:01:37Z

Context: --print crate-root-lint-levels (#139180) is only available for rustc and clippy-driver, while it would make sense for it to also be available for rustdoc (à la #83895.)

Not too sure about the stability of rustdoc --print=any or if this needs a MCP; strictly speaking, only rustdoc +nightly -Z unstable-options --print=crate-root-lint-levels would be required (and the rustdoc --print would be stabilized together with crate-root-lint-levels), but I guess that makes sense to have all the --prints for consistency.

For regression tests, not sure if ui or run-make is preferable, as run-make would need some sort of trait to avoid duplicating code between rustc() and rustdoc() (or just test rustdoc as it delegates to rustc):

rust/tests/run-make/print-crate-root-lint-levels/rmake.rs

Lines 82 to 88 in 021fc25

    
           fn check(CrateRootLintLevels { args, contains }: CrateRootLintLevels) { 
        
               let output = rustc() 
        
                   .input("lib.rs") 
        
                   .arg("-Zunstable-options") 
        
                   .print("crate-root-lint-levels") 
        
                   .args(args) 
        
                   .run();

@rustbot label +A-CLI +A-print-requests

rustbot · 2026-01-24T21:01:42Z

r? @notriddle

rustbot has assigned @notriddle.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Urgau · 2026-01-24T22:01:58Z

I could indeed see the --print being useful in rustdoc, but I'm still a bit curious what your use-case.
Would you be able describe it?

fmease · 2026-01-24T22:07:36Z

            return;
        }

+        if rustc_driver::print_crate_info(&*compiler.codegen_backend, sess, true)


Note: IINM, this won't be run if the input file is *.md or if --test is passed. Not sure what the consequences of that are.

Moreover, --print=crate-name doesn't really make sense for *.md inputs I feel like?

fmease · 2026-01-24T22:14:53Z

            }
        };

+        let prints =


I sense that there are certain rustc print requests which I don't think rustdoc can support.

E.g., I'm curious what will happen if you pass --print=link-args to rustdoc under your PR. Contrary to most other rustc print request that make rustc stop compilation early, link-args actually requires full analysis+codegen IINM … which rustdoc obv doesn't do. I guess it just doesn't print anything?

If so, that would be an example of a rustc print request that shouldn't be a legal rustdoc one.

There's also --print=native-static-libs that seems to require sth. similar.

E.g., I'm curious what will happen if you pass --print=link-args to rustdoc under your PR. Contrary to most other rustc print request that make rustc stop compilation early, link-args actually requires full analysis+codegen IINM … which rustdoc obv doesn't do. I guess it just doesn't print anything?

Yup, print_crate_info is a no-op for them as it's codegen_ssa that print them, and since the codegen isn't called, they don't print anything.

I'll filter the prints depending on if they make sense depending on the file type (.rs / .md / both) and action (doc / doctest / any).

ShE3py · 2026-01-25T00:14:46Z

I could indeed see the --print being useful in rustdoc, but I'm still a bit curious what your use-case. Would you be able describe it?

I'd like to diff the default lint-levels of two Rust versions in order to simplify updating the lints when I come back after a while (e.g. remove -W foo if foo was promoted to warn-by-default).

@rustbot author

rustbot · 2026-01-25T00:14:51Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

ShE3py · 2026-01-28T23:25:29Z

-    (option_env!("CFG_COMPILER_HOST_TRIPLE")).expect("CFG_COMPILER_HOST_TRIPLE")
+    env!("CFG_COMPILER_HOST_TRIPLE")


That was changed from env! to option_env! in the first commit of #13724, but not sure why this change was made or if it's still relevant as CI is green.

(Was looking looking for a #[expect] reason as removing the extra parentheses triggers deny-by-default clippy::option_env_unwrap)

Urgau · 2026-07-25T10:19:36Z

@ShE3py still interested in driving this PR forward?

ShE3py · 2026-07-26T11:18:15Z

Yup, prolly next month when I have time.

rustbot · 2026-08-30T18:21:50Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

ShE3py · 2026-08-30T20:50:21Z

+        // -W help
+        if sess.opts.describe_lints {
+            rustc_driver::describe_lints(sess, registered_lints);
+            return Ok(None);
+        }


Fixes -W help when running doctests:

$ rustdoc +nightly -Whelp --test /dev/null error: couldn't find file ``

View changes since the review

ShE3py · 2026-08-30T21:01:41Z

Copied from tests/run-make/print-crate-root-lint-levels/, replaced unexpected_cfgs with rustdoc::private_doc_tests.

View changes since the review

ShE3py · 2026-08-30T21:29:02Z

I have grouped the --print=options into four groups: crate, target, codegen and linker. Only the first two groups makes sense for Rustdoc imo.

I can somewhat far-fetch someone using rustdoc --print=host-tuple, but it might be better to initially restricts the print set to actual use cases, and then add more as people request them, e.g. not trying to make it as big as possible right from the start?

For Markdown files and doctests, --print would probably mean having one entry per ```code block```, at least for the crate group. Could be made in a follow-up PR, for now I flat out error.

@rustbot review

notriddle · 2026-08-31T14:59:47Z

@bors delegate+

The fix commits need squashed. But this looks okay, otherwise. r=me after squashing.

rust-bors · 2026-08-31T14:59:49Z

✌️ @ShE3py, you can now approve this pull request!

If @notriddle told you to "r=me" after making some further change, then please make that change and post @bors r=notriddle.

View changes since this delegation.

ShE3py · 2026-08-31T16:37:20Z

I've also added tests for rustdoc --test README.md; those are used in some repos and aren't currently tested (adding panic!() to doctest::test_markdown don't fail tests/run-make/rustdoc/ tests/rustdoc-ui/).

notriddle · 2026-08-31T18:34:37Z

@bors r+

rust-bors · 2026-08-31T18:34:41Z

📌 Commit d2c6c81 has been approved by notriddle

It is now in the queue for this repository.

@rustbot

rustdoc: add `--print` option Context: `--print crate-root-lint-levels` (rust-lang#139180) is only available for `rustc` and `clippy-driver`, while it would make sense for it to also be available for `rustdoc` (à la rust-lang#83895.) Not too sure about the stability of `rustdoc --print=any` or if this needs a MCP; strictly speaking, only `rustdoc +nightly -Z unstable-options --print=crate-root-lint-levels` would be required (and the `rustdoc --print` would be stabilized together with `crate-root-lint-levels`), but I guess that makes sense to have all the `--print`s for consistency. For regression tests, not sure if ui or run-make is preferable, as run-make would need some sort of trait to avoid duplicating code between `rustc()` and `rustdoc()` (or just test `rustdoc` as it delegates to `rustc`): https://github.com/rust-lang/rust/blob/021fc25b7a48f6051bee1e1f06c7a277e4de1cc9/tests/run-make/print-crate-root-lint-levels/rmake.rs#L82-L88 @rustbot label +A-CLI +A-print-requests

JonathanBrouwer · 2026-08-31T19:30:59Z

💔 I suspect this PR failed tests as part of a rollup
@bors r-

After fixing the problem, consider running a try job for the failed job before re-approving.

Link to failure: #162081 (comment)

rust-bors · 2026-08-31T19:31:08Z

This pull request was unapproved.

This PR was contained in a rollup (#162081), which was unapproved.

View changes since this unapproval

JonathanBrouwer · 2026-08-31T20:20:28Z

@bors try jobs=test-various,x86_64-msvc-*

rustdoc: add `--print` option try-job: test-various try-job: x86_64-msvc-*

rust-log-analyzer · 2026-08-31T21:03:16Z

The job test-various failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

---- [run-make] tests/run-make/rustdoc/doctest/markdown stdout ----

error: rmake recipe failed to complete
status: exit status: 1
command: cd "/checkout/obj/build/x86_64-unknown-linux-gnu/test/run-make/rustdoc/doctest/markdown/rmake_out" && env -u RUSTFLAGS -u __RUSTC_DEBUG_ASSERTIONS_ENABLED -u __STD_DEBUG_ASSERTIONS_ENABLED -u __STD_REMAP_DEBUGINFO_ENABLED AR="/wasi-sdk-34.0-x86_64-linux/bin/llvm-ar" BUILD_ROOT="/checkout/obj/build/x86_64-unknown-linux-gnu" CC="/wasi-sdk-34.0-x86_64-linux/bin/wasm32-wasip1-clang" CC_DEFAULT_FLAGS="-ffunction-sections -fdata-sections --target=wasm32-wasip1 -w" CXX="/wasi-sdk-34.0-x86_64-linux/bin/wasm32-wasip1-clang++" CXX_DEFAULT_FLAGS="-ffunction-sections -fdata-sections --target=wasm32-wasip1 -w" HOST_RUSTC_DYLIB_PATH="/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib" LD_LIBRARY_PATH=":/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/lib/rustlib/x86_64-unknown-linux-gnu/lib" LD_LIB_PATH_ENVVAR="LD_LIBRARY_PATH" LLVM_BIN_DIR="/checkout/obj/build/x86_64-unknown-linux-gnu/ci-llvm/bin" LLVM_COMPONENTS="aarch64 aarch64asmparser aarch64codegen aarch64desc aarch64disassembler aarch64info aarch64utils abi aggressiveinstcombine all all-targets amdgpu amdgpuasmparser amdgpucodegen amdgpudesc amdgpudisassembler amdgpuinfo amdgputargetmca amdgpuutils analysis arm armasmparser armcodegen armdesc armdisassembler arminfo armutils asmparser asmprinter avr avrasmparser avrcodegen avrdesc avrdisassembler avrinfo binaryformat bitreader bitstreamreader bitwriter bpf bpfasmparser bpfcodegen bpfdesc bpfdisassembler bpfinfo cas cfguard cgdata codegen codegentypes core coroutines coverage csky cskyasmparser cskycodegen cskydesc cskydisassembler cskyinfo debuginfobtf debuginfocodeview debuginfodwarf debuginfodwarflowlevel debuginfogsym debuginfologicalview debuginfomsf debuginfopdb demangle dlltooldriver dtlto dwarfcfichecker dwarflinker dwarflinkerclassic dwarflinkerparallel dwp engine executionengine extensions filecheck frontendatomic frontenddirective frontenddriver frontendhlsl frontendoffloading frontendopenacc frontendopenmp fuzzercli fuzzmutate globalisel hexagon hexagonasmparser hexagoncodegen hexagondesc hexagondisassembler hexagoninfo hipstdpar instcombine instrumentation interfacestub interpreter ipo irprinter irreader jitlink libdriver lineeditor linker loongarch loongarchasmparser loongarchcodegen loongarchdesc loongarchdisassembler loongarchinfo lto m68k m68kasmparser m68kcodegen m68kdesc m68kdisassembler m68kinfo mc mca mcdisassembler mcjit mcparser mips mipsasmparser mipscodegen mipsdesc mipsdisassembler mipsinfo mirparser msp430 msp430asmparser msp430codegen msp430desc msp430disassembler msp430info native nativecodegen nvptx nvptxcodegen nvptxdesc nvptxinfo objcarcopts objcopy object objectyaml option orcdebugging orcjit orcshared orctargetprocess passes plugins powerpc powerpcasmparser powerpccodegen powerpcdesc powerpcdisassembler powerpcinfo profiledata remarks riscv riscvasmparser riscvcodegen riscvdesc riscvdisassembler riscvinfo riscvtargetmca runtimedyld sandboxir scalaropts selectiondag sparc sparcasmparser sparccodegen sparcdesc sparcdisassembler sparcinfo support supportlsp symbolize systemz systemzasmparser systemzcodegen systemzdesc systemzdisassembler systemzinfo tablegen target targetparser telemetry textapi textapibinaryreader transformutils vectorize webassembly webassemblyasmparser webassemblycodegen webassemblydesc webassemblydisassembler webassemblyinfo webassemblyutils windowsdriver windowsmanifest x86 x86asmparser x86codegen x86desc x86disassembler x86info x86targetmca xray xtensa xtensaasmparser xtensacodegen xtensadesc xtensadisassembler xtensainfo" LLVM_FILECHECK="/checkout/obj/build/x86_64-unknown-linux-gnu/ci-llvm/bin/FileCheck" NODE="/node/bin/node" PYTHON="/usr/bin/python3" RUNNER="/wasmtime-v44.0.1-x86_64-linux/wasmtime run -Wexceptions -C cache=n --dir . --env RUSTC_BOOTSTRAP" RUSTC="/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustc" RUSTDOC="/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" SOURCE_ROOT="/checkout" TARGET="wasm32-wasip1" TARGET_EXE_DYLIB_PATH="/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/wasm32-wasip1/lib" __BOOTSTRAP_JOBS="4" __RMAKE_VERBOSE_SUBPROCESS_OUTPUT="1" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/run-make/rustdoc/doctest/markdown/rmake"
stdout: none
--- stderr -------------------------------
command failed at line 6
LD_LIBRARY_PATH="/checkout/obj/build/x86_64-unknown-linux-gnu/test/run-make/rustdoc/doctest/markdown/rmake_out:/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib::/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/lib/rustlib/x86_64-unknown-linux-gnu/lib" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "--test" "good.md" "--target=wasm32-wasip1"
output status: `exit status: 101`
=== STDOUT ===

running 4 tests
test good.md - Title (line 13) ... ignored
test good.md - Title (line 21) - compile fail ... ok
test good.md - Title (line 17) - compile ... ok

rust-bors · 2026-08-31T23:00:12Z

💔 Test for 8facfe3 failed: CI. Failed job:

try - test-various (web logs, enhanced plaintext logs)

rustbot assigned notriddle Jan 24, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jan 24, 2026

rustbot added A-CLI Area: Command-line interface (CLI) to the compiler A-print-requests Area: print requests (`--print=...`) labels Jan 24, 2026

This comment has been minimized.

Sign in to view

fmease reviewed Jan 24, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 25, 2026

rustbot added the A-run-make Area: port run-make Makefiles to rmake.rs label Jan 28, 2026

This comment has been minimized.

Sign in to view

ShE3py commented Jan 28, 2026

View reviewed changes

fmease mentioned this pull request Feb 20, 2026

feat(rustdoc): stabilize --emit flag #146220

Merged

This comment has been minimized.

Sign in to view

ShE3py added 2 commits August 30, 2026 15:05

doc: PrintKind

938b233

rustdoc: cleanup main_args() markdown handling

2e7e5cb

ShE3py force-pushed the rustdoc-print branch from 475fcfc to ca3a5e6 Compare August 30, 2026 18:21

ShE3py commented Aug 30, 2026

View reviewed changes

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 30, 2026

notriddle reviewed Aug 31, 2026

View reviewed changes

Comment thread src/librustdoc/lib.rs

notriddle approved these changes Aug 31, 2026

View reviewed changes

ShE3py added 3 commits August 31, 2026 18:00

rustdoc: add --print option

57cc38f

rustdoc: test --print option

736a14b

rustdoc: filter print kinds

0e6616b

ShE3py force-pushed the rustdoc-print branch from 1ebad10 to d2c6c81 Compare August 31, 2026 16:36

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 31, 2026

JonathanBrouwer mentioned this pull request Aug 31, 2026

Rollup of 4 pull requests #162081

Closed

rust-bors Bot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Aug 31, 2026

rustdoc: add tests for Markdown files

d571876

ShE3py force-pushed the rustdoc-print branch from d2c6c81 to d571876 Compare August 31, 2026 20:10

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request Aug 31, 2026

Auto merge of #151618 - ShE3py:rustdoc-print, r=<try>

8facfe3

rustdoc: add `--print` option try-job: test-various try-job: x86_64-msvc-*

	fn check(CrateRootLintLevels { args, contains }: CrateRootLintLevels) {
	let output = rustc()
	.input("lib.rs")
	.arg("-Zunstable-options")
	.print("crate-root-lint-levels")
	.args(args)
	.run();

		(option_env!("CFG_COMPILER_HOST_TRIPLE")).expect("CFG_COMPILER_HOST_TRIPLE")
		env!("CFG_COMPILER_HOST_TRIPLE")

Uh oh!

Uh oh!

Conversation

ShE3py commented Jan 24, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jan 24, 2026

Uh oh!

This comment has been minimized.

Urgau commented Jan 24, 2026

Uh oh!

Uh oh!

fmease Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

fmease Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

fmease Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

ShE3py Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

ShE3py commented Jan 25, 2026

Uh oh!

rustbot commented Jan 25, 2026

Uh oh!

This comment has been minimized.

ShE3py Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

Urgau commented Jul 25, 2026

Uh oh!

ShE3py commented Jul 26, 2026

Uh oh!

rustbot commented Aug 30, 2026

Uh oh!

ShE3py Aug 30, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShE3py Aug 30, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShE3py commented Aug 30, 2026

Uh oh!

Uh oh!

notriddle commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

ShE3py commented Aug 31, 2026

Uh oh!

notriddle commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

JonathanBrouwer commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

JonathanBrouwer commented Aug 31, 2026

Uh oh!

This comment has been minimized.

rust-log-analyzer commented Aug 31, 2026

Uh oh!

rust-bors Bot commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

ShE3py commented Jan 24, 2026 •

edited by rustbot

Loading

ShE3py Aug 30, 2026 •

edited by rustbot

Loading

ShE3py Aug 30, 2026 •

edited by rustbot

Loading

notriddle commented Aug 31, 2026 •

edited

Loading