Skip to content

feat: [python] add api.md generation support - #10854

Closed
iscai-msft wants to merge 5 commits into
microsoft:mainfrom
iscai-msft:feat/python-api-md
Closed

iscai-msft wants to merge 5 commits into
microsoft:mainfrom
iscai-msft:feat/python-api-md

Conversation

@iscai-msft

Copy link
Copy Markdown
Member

Summary

Adds opt-in generate-api-md emitter option that generates an api.md file containing the public API surface of the generated Python SDK.

Resolves: #10089

Changes

  • generate-api-md option — boolean, defaults to false. When enabled, runs apistubgen after code generation and formatting.
  • Pipeline: preprocess → codegen → black → apistubgen → api.md
  • Token generation: Uses --code-model-path to generate APIView tokens directly from the YAML code model (fast, no package install needed)
  • Markdown conversion: Python script (export_apiview_markdown.py) converts token JSON → api.md (port of Export-APIViewMarkdown.ps1, avoids pwsh dependency)
  • Error handling: Failures emit a warning but never block SDK generation
  • Native-only: Only runs in native Python path (not Pyodide)

Dependencies

Related

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>
@pkg-pr-new

pkg-pr-new Bot commented Jun 1, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-python@10854

commit: c2fb2f9

@github-actions

github-actions Bot commented Jun 1, 2026 •

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/http-client-python
Show changes

@typespec/http-client-python - feature ✏️

Add generate-api-md emitter option to generate an api.md file containing the public API surface. When enabled, the emitter runs apiview-stub-generator to produce a token JSON file and converts it to markdown. Requires apiview-stub-generator to be installed in the Python environment.,> ,> yaml,> # tspconfig.yaml,> options:,> "@typespec/http-client-python":,> generate-api-md: true,>

@azure-sdk-automation

azure-sdk-automation Bot commented Jun 1, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

]);

// Find the generated token JSON file
const tokenFiles = fs.readdirSync(apiviewOutDir).filter((f: string) => f.endsWith(".json"));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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;

@msyyc Yuchao Yan (msyyc) Jun 2, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better to add test cases for the new option.

iscai-msft and others added 4 commits June 2, 2026 16:27
- 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>
@iscai-msft
iscai-msft marked this pull request as draft June 2, 2026 20:57
@microsoft-github-policy-service microsoft-github-policy-service Bot added the stale Mark a PR that hasn't been recently updated and will be closed. label Jun 17, 2026
@microsoft-github-policy-service

Copy link
Copy Markdown
Contributor

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 stale label.

@microsoft-github-policy-service

Copy link
Copy Markdown
Contributor

Hi @iscai-msft. The PR will be closed since the PR has no update for 28 days. If this is still relevant please reopen.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:client:python Issue for the Python client emitter: @typespec/http-client-python stale Mark a PR that hasn't been recently updated and will be closed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[python] feature request - add api.md to generation

2 participants