microsoft / microsoft/typespec
[python] feature request - add api.md to generation
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
Add a step to the Python TypeSpec emitter to **automatically generate an api.md file** as part of the emitter pipeline.
### Prerequirements:
- ~Export-APIViewMarkdown.ps1 should be available under `eng/emitters/scripts` or `eng/common/scripts`. (cc/ @timotheeguerin)~ addressed here: https://github.com/microsoft/typespec/pull/10096
### Scope
* Generate **api.md**.
* By default, it should be generated, but allow for an **opt‑out**.
* Any apistubgen errors should warn and continue, and NOT block.
* The api.md file should NOT be included in the whl (exclude from pyproject.toml/setup.py).
### Proposed implementation
Extend the Python emitter pipeline from:
preprocess → generate → format (black)
to:
preprocess → generate → format (black) → apistubgen → api.md
1. Run the `apistubgen` command on the package to generate the token JSON file. This file will _not_ be added to the package artifacts.
2. Pass the token file to Export-APIViewMarkdown.ps1 on the JSON token file to generate the api markdown file.
Contributor guide
Assessment
This issue has not been assessed yet.