DOC generate API pages for empty modules and render aliases#1469
Open
biefan wants to merge 1 commit intoAzure:mainfrom
Open
DOC generate API pages for empty modules and render aliases#1469biefan wants to merge 1 commit intoAzure:mainfrom
biefan wants to merge 1 commit intoAzure:mainfrom
Conversation
Signed-off-by: biefan <70761325+biefan@users.noreply.github.com>
Author
|
@microsoft-github-policy-service agree |
romanlutz
reviewed
Mar 15, 2026
Contributor
romanlutz
left a comment
romanlutz
left a comment
There was a problem hiding this comment.
Looks good! Just want to try it out locally before merging
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the documentation build script that generates MyST API reference markdown from griffe JSON so that re-exported names (aliases) are represented and modules with no detected public members are handled more explicitly.
Changes:
- Add alias rendering and an “Aliases” section to per-module API pages.
- Generate per-module pages for all collected modules and show an explicit “no public API members” message when empty.
- Improve index previews to include functions and aliases (not just classes), with a fallback message for empty modules.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
260
to
270
| members = data.get("members", []) | ||
| member_count = len(members) | ||
| slug = mod_name.replace(".", "_") | ||
| classes = [m["name"] for m in members if m.get("kind") == "class"][:8] | ||
| preview = ", ".join(f"`{c}`" for c in classes) | ||
| if len(classes) < member_count: | ||
|
|
||
| classes = [f"`{m['name']}`" for m in members if m.get("kind") == "class"] | ||
| functions = [f"`{m['name']}()`" for m in members if m.get("kind") == "function"] | ||
| aliases = [f"`{m['name']}`" for m in members if m.get("kind") == "alias"] | ||
| preview_items = (classes + functions + aliases)[:8] | ||
| preview = ", ".join(preview_items) | ||
| if member_count > len(preview_items): | ||
| preview += f" ... ({member_count} total)" |
Comment on lines
+253
to
+254
| md_path.write_text(content, encoding="utf-8") | ||
| print(f"Written {md_path} ({len(members)} members)") |
romanlutz
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This updates
build_scripts/gen_api_md.pyto make generated API docs more complete and avoid broken links.What changed
## Aliasessection.No public API members were detected for this module.Why
doc/api/index.md.Validation
uv run --with ruff ruff check build_scripts/gen_api_md.pymissing_links 0check for links indoc/api/index.mdFixes #653