Repository navigation
docs(examples): Standardize structure and content across docs/examples/ #1746
Description
Currently, examples found under /docs do not have a cohesive structural pattern. As a result, they are inconsistent and confusing to parse, especially for a new user:
Key Featurescan be described for one example but not for others [1, 2].UsageandConceptssections are ambiguous and may refer to only one of multiple listed examples [1, 2].- Some instances of deep dives into concepts in the README itself [1]
- No README [1, 2]
- Missing references to scripts [1a, 1b]
- Website references the example scripts but doesn't link to them [1]
I propose that
- Examples as standalone scripts with standardized docstrings (high-level description, selective context/explanation, and usage (
uv run)).- If the example requires more detail than a docstring to be useful, then it might be a tutorial or a documentation gap.
- Multi-artifact/complex examples (examples that require more than one file)
- Can be isolated in their own directory with a thorough README as needed.
- Directory READMEs ([1, 2] only contain
- A high level description
- Table for navigating the available examples.
- The website examples page link directly to each directory of examples and maintain a few highlight/deep-dive examples.
Implementation Roadmap
| Group | Target Directories | PR |
|---|---|---|
| 1. Foundation & Presets | primitives/, sampling/, agents/ |
#1747, #1752 (merged) |
| 2. Core Prompting & Context | instruct_validate_repair/, generative_stubs/, context/, sessions/ |
#1753 (merged) |
| 3. Data, Extraction & RAG | rag/, information_extraction/, mobject/, mify/ |
#1764 (merged) |
| 4. Adapters & Model Capabilities | intrinsics/, granite-switch/, aLora/, sofai/ |
#1765 |
| 5. Tools, Plugins & Interop | tools/, plugins/, requirements/, mcp/, library_interop/ |
#1766 (merged) |
| 6. Serving & Multimodal | m_serve/, m_decompose/, audio_text_models/, image_text_models/, mini_researcher/ |
#1774 (merged) |
| 7. Async, Telemetry & Infrastructure | async/, streaming/, bedrock/, telemetry/, melp/, helper/ |
#1776 (merged) |
| 8. Tutorials, Notebooks & Root Index | tutorial/, notebooks/, root README.md, root scripts |
#1777 (merged) |
Activity
[-]examples: Standardize structure and content across `docs/examples/`[/-][+]docs(examples): Standardize structure and content across `docs/examples/`[/+]docs(examples): standardize adapter, granite-switch, aLoRA, and SOFAI…
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!
rafvasq commentedon Nov 2, 2026
@Ashutosh2407 thanks for reaching out, but this issue is just about complete at this point. Feel free to look for another to contribute!
Ashutosh2407 commentedon Nov 3, 2026
Thanks @rafvasq . I will keep looking.