Add new API generation tool#4666
Merged
Merged
Conversation
This commit introduces a new tool for generating API documentation for the azure-sdk-for-rust repository. The tool includes a command-line interface, diagnostics, and a model for representing the API structure. The rendering logic supports two output formats: APIView and Markdown. The APIView format produces a structured JSON output, while the Markdown format generates Rust code snippets. Additionally, the Rust toolchain configuration has been updated to include the `rustc-dev` component, which is necessary for development purposes.
This update introduces the extraction and rendering of explicit trait implementation blocks in the API model. It includes enhancements to the extraction logic to identify and include trait implementations alongside their associated members. Additionally, the rendering functions have been updated to properly format these implementations in the output, ensuring they are navigable and correctly represented in the API documentation. Tests have been added to verify the correct rendering of trait implementations, ensuring that the new functionality works as intended.
heaths
requested review from
LarryOsterman,
RickWinter,
danieljurek and
xirzec
as code owners
This update introduces a new function to handle the rendering of self parameters in a more idiomatic Rust style. The changes ensure that receiver parameters are displayed as `self`, `&self`, or `&mut self` instead of `self: Self`, `self: &Self`, or `self: &mut Self`. This improves the clarity and consistency of the generated API documentation.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new standalone CLI tool, generate_api, under eng/tools/, intended to eventually replace generate_api_report. It generates public-API artifacts for a Rust crate by running cargo metadata + cargo rustdoc --output-format json, normalizing the rustdoc JSON into a tool-owned intermediate model, and rendering that model to either Markdown (API.md) or APIView (apiview.json). A notable feature is extraction/rendering of explicit (non-derived) trait impl blocks with navigable members. The rustc-dev component is added to the pinned nightly toolchain to enable a future move toward direct librustdoc/HIR integration.
Changes:
- New
generate_apibin crate (cli, diagnostics, driver, extract, model, output, render/apiview, render/markdown) plus README/PLAN docs, wired into theeng/toolsworkspace withclapadded to workspace deps. - Adds
rustc-devtoeng/tools/rust-toolchain.tomland updates.vscode/settings.json(linked projects, reordered cmake setting). - Unit tests covering trait-impl extraction and both renderers.
Show a summary per file
| File | Description |
|---|---|
| eng/tools/rust-toolchain.toml | Adds rustc-dev component to the nightly toolchain |
| eng/tools/Cargo.toml | Registers generate_api member and adds clap workspace dependency |
| eng/tools/generate_api/Cargo.toml | New crate manifest inheriting workspace deps |
| eng/tools/generate_api/build.rs | Reads toolchain channel from rust-toolchain.toml into TOOLCHAIN_CHANNEL |
| eng/tools/generate_api/src/main.rs | Entry point: parse args, load model, render, write output |
| eng/tools/generate_api/src/cli.rs | clap-based CLI args and Request/OutputFormat types |
| eng/tools/generate_api/src/diagnostics.rs | Simple stdout/stderr logging helpers |
| eng/tools/generate_api/src/driver.rs | Runs cargo metadata/rustdoc and caches workspace crate models |
| eng/tools/generate_api/src/extract.rs | Converts rustdoc JSON into the shared model (re-exports, derives, trait impls) |
| eng/tools/generate_api/src/model.rs | Shared intermediate API model and item-kind ordering |
| eng/tools/generate_api/src/output.rs | Output path creation and file writing (&PathBuf param flagged) |
| eng/tools/generate_api/src/render/mod.rs | Render module declarations |
| eng/tools/generate_api/src/render/markdown.rs | Markdown renderer (member-placement issue flagged) |
| eng/tools/generate_api/src/render/apiview.rs | APIView token renderer + validation and tokenizer |
| eng/tools/generate_api/README.md / PLAN.md | Tool usage and design documentation |
| .vscode/settings.json | Adds rust-analyzer linked projects; reorders cmake setting |
Review details
- Files reviewed: 17/17 changed files
- Comments generated: 3
- Review effort level: Medium
This update introduces new functions to flatten whitespace and remove unnecessary spaces around path separators in attributes. These changes ensure that the review output remains consistent and source-like, particularly for multiline attributes. Additional tests have been added to verify the correctness of these normalizations.
- Extracted command execution into a reusable function to reduce code duplication in `driver.rs`. - Simplified item implementation retrieval in `extract.rs` by introducing a helper function. - Added sorting functionality for API items in `model.rs` to ensure consistent ordering during rendering. - Updated rendering functions in `apiview.rs` and `markdown.rs` to utilize the new sorting method for improved output consistency.
Address PR Azure#4666 review feedback in the shared output and rendering layers. Render inherent members inside source-shaped impl blocks for both review and APIView output, simplify the trait impl re-export plumbing, and accept &Path in write_file to satisfy Clippy. Update the durable plan to reflect the final inherent impl rendering decision. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xirzec
approved these changes
Jun 26, 2026
Make the review format the default, add the --no-docs switch for APIView output, and refactor APIView rendering to use a forward-compatible RenderOptions struct. Update the README and durable plan to document the new CLI behavior and the preference for options structs over threaded booleans in renderer configuration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xirzec
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce a new command-line tool for generating API documentation in the azure-sdk-for-rust repository. This tool includes diagnostics, a model for API structure, and supports output in both APIView and Markdown formats.
Enhancements include the extraction and rendering of explicit trait implementations, ensuring accurate representation in the documentation. The Rust toolchain configuration has been updated to include the
rustc-devcomponent for development purposes.Tests have been added to verify the correct rendering of trait implementations.
This will replace generate_api_report in a subsequent PR.
Fixes Azure/azure-sdk-tools#12698
Fixes Azure/azure-sdk-tools#15383
Fixes Azure/azure-sdk-tools#15384
Fixes Azure/azure-sdk-tools#15385
Fixes Azure/azure-sdk-tools#15445