rustdoc: accept `--out-dir` and soft-deprecate `--output`

[jyn514]

Rustc uses --out-dir, but rustdoc rejects it. This is an unnecessary incompatibility; rustdoc should accept --out-dir too. Accepting --output was a mistake, but it's stable and used in almost literally every run by cargo, so we realistically can't even warn on it. We should document that --out-dir is the recommended option, though.

Once --out-dir has been accepted for several releases, we could consider starting to warn on --output, but I don't suggest committing to that now.

[jyn514]

@rfcbot fcp merge

[rfcbot]

Team member @jyn514 has proposed to merge this. The next step is review by the rest of the tagged team members:

• @CraftSpider
• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @camelid
• @jsha
• @jyn514
• @ollie27

Concerns:

• churn resolved by rustdoc: accept --out-dir and soft-deprecate --output #91260 (comment)
• consistency with rustc resolved by rustdoc: accept --out-dir and soft-deprecate --output #91260 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[jyn514]

Note that this will still leave an inconsistency - rustdoc will treat -o as a synonym for --out-dir, while rustc treats -o as a filename and not a directory. This isn't great for modes where it makes sense to output a single file, such as --output-format json. I think it's still better than the current situation though (where -o is a synonym for --output).

[Manishearth]

@rfcbot reviewed

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[jyn514]

Mentoring instructions:

1. Add a new out-dir option in src/librustdoc/lib.rs.
2. Change the output option to point to out-dir:

   rust/src/librustdoc/lib.rs

   Line 281 in 686e313

   stable("o", |o| o.optopt("o", "output", "where to place the output", "PATH")),

Feel free to ask for help, but please do so on Zulip or Discord to avoid pinging the whole team :)

[0xPoe]

@rustbot claim