Azure / Azure/azure-sdk-tools

[Python APIView] Add markdown API file to the Python repo

Open
#12,851 0 comments 0 reactions 1 assignee Claimed by @tjprescott View on GitHub
APIView P0 Python
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

There should be an API md file added to the Python repo from the APIView.
- Note: We don't want to have to go to the website for this.
- Note: We can actually download this file now, but only on the server side. It's not an APIView feature, it's a browser feature.

**Motivation**:
- Provides agents with a CLI tool that can generate the markdown file to conveniently reason about the API without the agent committing output to the repo
- Allowing GH Copilot to address comments automatically and directly in the PRs (if we can get the plumbing for TSP <-> SDK figured out)
- Enabling API reviews directly within the PR, making it easier to reference code changes as needed
- Minor: Ensuring the service team checks early on that API changes are intentional and correct, instead of waiting until the release step

**TODO**:
- [x] 1. ~Add parser option to get the output as an md file with option `--md`. (Make this an addition to the JSON file. It should be added to generated artifacts.)~ Add a JSON -> md token file conversion script.
- [x] 2. azpysdk CLI -- make sure it can generate the apiview.
- [x] a. Once this is done, Jenny can add it to MCP and we should be able to ask in Copilot chat for it to run this.
- [ ] b. Double check with Shanghai team that they can do this for mgmt libs + which CI to update.
- [ ] 3. Discuss with Izzy about updating emitter to generate api.md.
- [ ] Every time there's a new parser change, we want to run the spector tests for autorest.python. So integrate this extra step into the parser CI.
- [ ] 4. Check with Scott about ensuring that old and new API.md files are both generated from the same/latest parser version, so that diff doesn't trigger on parser updates. --> most likely a pipeline that will auto do this.
- [ ] 5. Add the API.md file to the sdk folder. Ensure that pyproject.toml/setup.py are updated to exclude the API.md folder (+ update the typespec client generator.)
- [ ] 6. Instruct coding agent to fix issues in the code based on api.md comments. (The classifier work might be useful here. Update copilot custom instructions to classifier + show it tsp-location.yaml/regenerate based on updated TSP.)

_____ PHASE 2 ______
- [ ] 7. BEFORE adding any CI CHECKS: Draft email with Laurent to partners about generation/release process that api.md will be added.
- Talk to architects first about process: 1. always review in PR about this api.md diff 2. If there are issues here, then switch to APIView.
- Establish clear dates.
- Talk to Laurent about phrasing of the email. We want to make it clear that this will not yet replace APIView, but will come first.
- [ ] 8. Create post in Python channel for this as well.
- [ ] 9. CI step that compares the old and new md for the diff. If there's a diff, service team needs to fix and update and push the new version. When the diff above fails, there should be a one line azpysdk tool call to run locally.
- Start with warnings then enable it on a specific date.
______
Open Questions:
* Do we want to do a diff CI check even for beta versions? or if the previous version was a beta? Or do we only want to compare to previous stable versions?

_____ LONG TERM BONUS_____
- For features that are on APIView that can't be added to GH, we can maybe look to make a VSCode extension for APIView since we'll have more control.

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.