Repository navigation
feat: [python] add api.md generation support - #10854
iscai-msft wants to merge 5 commits into
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>
commit: |
|
All changed packages have been documented.
Show changes
|
|
You can try these changes here
|
| ]); | ||
|
|
||
| // Find the generated token JSON file | ||
| const tokenFiles = fs.readdirSync(apiviewOutDir).filter((f: string) => f.endsWith(".json")); |
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.
| target: NoTarget, | ||
| format: { details: "apistubgen did not produce a token JSON file" }, | ||
| }); | ||
| return; |
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>
|
Hi @iscai-msft. Your PR has had no update for 14 days and it is marked as a stale PR. If it is not updated within 14 additional days, the PR will automatically be closed. If you want to refresh the PR, please remove the |
|
Hi @iscai-msft. The PR will be closed since the PR has no update for 28 days. If this is still relevant please reopen. |
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