Migrate Rustdoc JSON

Migrate Rustdoc's JSON output to newer format versions.

Why is this useful?

There are several tools that read Rustdoc's JSON format, the largest of which being cargo-semver-checks and cargo-public-api.

These tools either support only a specific format version of the JSON or do not support comparing JSON with different format versions. This is an issue for projects that depend on the compiler's internal APIs (rustc drivers) and for projects that require an older, unsupported compiler.

Installation

You can install the latest release of migrate_rustdoc_json with cargo install:

cargo install migrate_rustdoc_json --locked

You can install the latest unstable version from Git:

cargo install --git https://github.com/BD103/migrate_rustdoc_json --locked

Quick Start

migrate_rustdoc_json --input path/to/rustdoc.json --to-version latest > migrated.json

Usage

In order to migrate Rustdoc's JSON output, you must first build the original JSON:

# Build Rustdoc JSON for a crate.
cargo +nightly rustdoc -- -Zunstable-options --output-format json

You'll likely need to change +nightly to a specific toolchain. You may also be interested in passing --document-hidden-items and --document-private-items.

Once you've built the JSON, you can use migrate_rustdoc_json to migrate it to a later version:

# Migrate the Rustdoc JSON to a newer format version.
migrate_rustdoc_json --input target/doc/crate_name.json --to-version 45 > migrated.json

migrate_rustdoc_json prints the migrated JSON to stdout, which is why you need to pipe it to a file with > migrated.json. This tool only supports migrating to newer format versions (such as v43 to v45). Migrating down (such as v46 to v42) is unsupported.

Compatibility

merge_rustdoc_json Version	Format Version
v0.4.0-dev	v41..=v46
v0.3.0	v41..=v46
v0.2.0	v41..=v45
v0.1.0	v41..=v45

This table shows which range of format versions a given release of merge_rustdoc_json supports. merge_rustdoc_json can read any JSON within the range, and can migrate it to any greater version within the range.

History

This tool was originally created for the Bevy Linter to assist with updating to newer versions of the Rust compiler and clippy_utils. Since neither dependency provides an internal changelog and each release requires a different Rust compiler version, migrate_rustdoc_json was created to allow viewing the breaking changes with cargo-semver-checks.

License

migrate_rustdoc_json is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contributing

Check out CONTRIBUTING.md if you're interested in helping out!

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.