feat: [python] add api.md generation support#10854
Draft
iscai-msft wants to merge 5 commits into
Draft
Conversation
Add opt-in 'generate-api-md' emitter option that generates an api.md file containing the public API surface of the generated SDK. Pipeline: preprocess → codegen → black → apistubgen → api.md Implementation: - New 'generate-api-md' option (defaults to false, opt-in) - Runs apistubgen with --code-model-path for fast token generation directly from the YAML code model (no package install needed) - Python script converts APIView token JSON to markdown (port of Export-APIViewMarkdown.ps1, avoids pwsh dependency) - Failures emit a warning but never block SDK generation - Only runs in native Python path (not Pyodide) Requires apiview-stub-generator with --code-model-path support (azure-sdk-tools PR #15104). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
iscai-msft
requested review from
ChenxiJiang333,
catalinaperalta,
l0lawrence,
lmazuel,
msyyc,
tadelesh and
timotheeguerin
as code owners
microsoft-github-policy-service
Bot
added
the
emitter:client:python
commit: |
Contributor
|
All changed packages have been documented.
Show changes
|
|
You can try these changes here
|
msyyc
reviewed
Jun 2, 2026
| ]); | ||
|
|
||
| // Find the generated token JSON file | ||
| const tokenFiles = fs.readdirSync(apiviewOutDir).filter((f: string) => f.endsWith(".json")); |
Contributor
There was a problem hiding this comment.
Does apiview tool generate a stable name like apiview_python.json? If yes, we could check that name directly to avoid find wrong json file.
msyyc
reviewed
Jun 2, 2026
| target: NoTarget, | ||
| format: { details: "apistubgen did not produce a token JSON file" }, | ||
| }); | ||
| return; |
Contributor
There was a problem hiding this comment.
Better to add test cases for the new option.
- Use stable token filename ({package_name}_python.json) instead of
scanning for any .json file in the output directory
- Add emitter tests for export_apiview_markdown.py script
- Add changeset for the feature
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Default generate-api-md to true. Silently skip if apiview-stub-generator is not installed (only warn if it is installed but fails). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ensures api.md generation is always available when using native Python. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
2 participants
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.
Summary
Adds opt-in
generate-api-mdemitter option that generates anapi.mdfile containing the public API surface of the generated Python SDK.Resolves: #10089
Changes
generate-api-mdoption — boolean, defaults tofalse. When enabled, runsapistubgenafter code generation and formatting.preprocess → codegen → black → apistubgen → api.md--code-model-pathto generate APIView tokens directly from the YAML code model (fast, no package install needed)export_apiview_markdown.py) converts token JSON → api.md (port ofExport-APIViewMarkdown.ps1, avoidspwshdependency)Dependencies
apiview-stub-generatorwith--code-model-pathsupport (azure-sdk-tools#15104)Related