Tracking Issue for `--output-format` flag for `cargo rustdoc`

[weihanglo]

Summary

Original issue: #12103
Implementation: #12252
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#output-format-for-rustdoc

This flag determines the output format of cargo rustdoc, providing tools a way to lean on rustdoc's experimental JSON format.

Unresolved Issues

• Make sure it doesn't cause errors with --open flag when opening JSON file.
• Interaction with -Z rustdoc-scrape-examples. Does the JSON include the scraped data? Or should scraping be disabled when generating the JSON?
• Add it to cargo doc as well? We might need to address the output JSON name conflict. cargo rustdoc --output-format=json sometimes doesn't rebuild for different versions of same crate name. #16291

Future Extensions

No response

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[charmitro]

Unresolved Issues

* [ ]  Make sure it doesn't cause errors with `--open` flag when opening JSON file.

* [ ]  Interaction with [`-Z rustdoc-scrape-examples`](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#scrape-examples). Does the JSON include the scraped data? Or should scraping be disabled when generating the JSON?

* [ ]  Add it to `cargo doc` as well? We might need to address the output JSON name conflict.

I'll try to have some answers for these three unresolved issues and reach back with my observations.

[charmitro]

Make sure it doesn't cause errors with --open flag when opening JSON file.

This has been tested on macOS and works as intended. Unfortunately, I do not have access to a Windows machine to perform the same test there.

Interaction with -Z rustdoc-scrape-examples. Does the JSON include the scraped data? Or should scraping be disabled when generating the JSON?

I cannot see the scraped data in the JSON, but it is visible in the HTML documentation. @weihanglo, it would be advisable to ensure that if both -Z rustdoc-scrape-example and --output-format json flags are used together, an error message is generated for the user.

Add it to cargo doc as well? We might need to address the output JSON name conflict.

Yes, I believe we should also add it to cargo doc. Why conflict though? Does cargo doc generate a different HTML file compared to cargo rustdoc?

[tkr-sh]

cargo doc --no-deps --output-format=json still put the dependencies crates paths in { "paths": ... }. Is this expected ?

[weihanglo]

The unstable --output-format option is not yet supported in cargo doc. And cargo rustdoc doesn't support --no-deps. I am not sure which one you were talking about. If it is about the rustdoc JSON schema, probably a better place to ask is in rust-lang/rust or the tracking issue rust-lang/rust#76578.