Repository navigation
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationp2Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.
Description
As part of the review for #1710, @planetf1 found more improvements that we have decided to address in a separate issue and PR. We may need to discuss this before making changes.
Mainly we want to make sure:
- How we want to address linking examples files used in
uv runand if we want to be more consistent with how we refer to the examples. Also, at couple of places, we want to make sure to fix linking to exapmple(s) instead of directory and verify any already linked path(s) are still correct. As, mentioned in the original comment, fixing all of this needs judgement on where links go, not a mechanical wrap. docs/docs/examples/*.mdand few other files in thedocs/docs/exampleshas Source file: lines with no link, so link them.- Investigate if we can add a pytest check that walks docs/examples/*/README.md both ways: every link resolves to a real file (catches the two bad links above), and every .py/.ipynb in the directory is linked from somewhere (catches gaps like these).
Below are the improvements suggested by @planetf1 in his original review comment:
- ~55 more example files across 9 READMEs (async, bedrock, intrinsics, plugins, streaming) are named only in uv run fences or not at all — plugins misses 7 builtin_.py files, intrinsics misses uncertainty_ollama.py. There are also a couple of existing links that are just wrong: mcp/README.md links to a path with no extension, docs/examples/README.md links to a directory instead of a file. Fixing all of this needs judgement on where links go, not a mechanical wrap. This PR, a follow-up PR, or an issue — up to you. Separately, we could add a pytest check that walks docs/examples//README.md both ways: every link resolves to a real file (catches the two bad links above), and every .py/.ipynb in the directory is linked from somewhere (catches gaps like these). Would stop this drifting again regardless of which option you pick.
docs/docs/examples/*.md has Source file: lines with no link (e.g. traced-generation-loop.md:13) — same problem, docs site side, needs GitHub URLs not relative links since Docusaurus resolves against its own routes. In scope here or separate? - docs/docs/examples/*.md has Source file: lines with no link (e.g. traced-generation-loop.md:13) — same problem, docs site side, needs GitHub URLs not relative links since Docusaurus resolves against its own routes. In scope here or separate?
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationp2Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.
Activity
planetf1 commentedon Oct 12, 2026
Another thing to consider is whether we can/should automate these checks in future to ensure the docs stay up to date as demos are added/removed. Not essential, but may reduce effort long term.
Ashutosh2407 commentedon Oct 31, 2026
Hi, I’m new to this project and would like to work on this issue if it’s still open and valid. Could you assign it to me? Thanks!