microsoft / microsoft/typespec

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

Open
#10,089 4 comments 0 reactions 1 assignee Claimed by @iscai-msft View on GitHub
emitter:client:python
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.