Skip to content

docs: link example references in uv run and other related improvements #1730

Open

Description

@spzala

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 run and 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/*.md and few other files in the docs/docs/examples has 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?

Activity

  1. planetf1 commented on Oct 12, 2026

    @planetf1
    Contributor

    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.

  2. self-assigned this
    on Oct 12, 2026
  3. added
    documentationImprovements or additions to documentation
    p2Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.
    on Oct 30, 2026
  4. Ashutosh2407 commented on Oct 31, 2026

    @Ashutosh2407

    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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationp2Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions