Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jonathanhefner wants to merge 7 commits into
base:main
Choose a base branch
from
Open

Type-check docstring code examples via companion files and unified sync script #2119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
925d45c
Replace `update_readme_snippets.py` with unified `sync_snippets.py`
jonathanhefner Feb 19, 2026
98b1ec2
Support path-less `#region` markers in `sync_snippets.py`
jonathanhefner Feb 20, 2026
bc49384
Extract docstring code examples into type-checked companion files
jonathanhefner Feb 20, 2026
6561cc8
Document docstring snippet conventions in `CLAUDE.md`
jonathanhefner Feb 20, 2026
b508a84
Document markdown snippet syncing in `CLAUDE.md`
jonathanhefner Feb 20, 2026
9f95151
Restructure snippet system docs into shared intro with subsections
jonathanhefner Feb 20, 2026
6101e44
Remove "Full example" links from `README.v2.md`
jonathanhefner Feb 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/shared.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
- name: Install dependencies
run: uv sync --frozen --all-extras --python 3.10

- name: Check README snippets are up to date
run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
- name: Check snippets are up to date
run: uv run --frozen python scripts/sync_snippets.py --check
6 changes: 3 additions & 3 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
language: fail
files: ^README\.md$
- id: readme-snippets
name: Check README snippets are up to date
entry: uv run --frozen python scripts/update_readme_snippets.py --check
name: Check snippets are up to date
entry: uv run --frozen python scripts/sync_snippets.py --check
language: system
files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
pass_filenames: false
66 changes: 66 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
- Update config rev
- Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
# region MyClass_do_thing_basic
result = obj.do_thing("arg")
print(result)
# endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
Example:
<!-- snippet-source #MyClass_do_thing_basic -->
```python
result = obj.do_thing("arg")
print(result)
```
<!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Type-check docstring code examples via companion files and unified sync script#2119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

jonathanhefner
wants to merge
7
commits into

base:main
Choose a base branch

from

 Open


Type-check docstring code examples via companion files and unified sync script
#2119
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
925d45c

Replace `update_readme_snippets.py` with unified `sync_snippets.py`


jonathanhefner Feb 19, 2026
98b1ec2

Support path-less `#region` markers in `sync_snippets.py`


jonathanhefner Feb 20, 2026
bc49384

Extract docstring code examples into type-checked companion files


jonathanhefner Feb 20, 2026
6561cc8

Document docstring snippet conventions in `CLAUDE.md`


jonathanhefner Feb 20, 2026
b508a84

Document markdown snippet syncing in `CLAUDE.md`


jonathanhefner Feb 20, 2026
9f95151

Restructure snippet system docs into shared intro with subsections


jonathanhefner Feb 20, 2026
6101e44

Remove "Full example" links from `README.v2.md`


jonathanhefner Feb 23, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


4 changes: 2 additions & 2 deletions
.github/workflows/shared.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -91,5 +91,5 @@ jobs:
 - name: Install dependencies
 run: uv sync --frozen --all-extras --python 3.10

 - name: Check README snippets are up to date
 run: uv run --frozen scripts/update_readme_snippets.py --check --readme README.v2.md
 - name: Check snippets are up to date
 run: uv run --frozen python scripts/sync_snippets.py --check

6 changes: 3 additions & 3 deletions
.pre-commit-config.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -62,8 +62,8 @@ repos:
 language: fail
 files: ^README\.md$
 - id: readme-snippets
 name: Check README snippets are up to date
 entry: uv run --frozen python scripts/update_readme_snippets.py --check
 name: Check snippets are up to date
 entry: uv run --frozen python scripts/sync_snippets.py --check
 language: system
 files: ^(README\.v2\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
 files: ^(README\.v2\.md|examples/.*\.py|src/mcp/.*\.py|docs/.*\.md|scripts/sync_snippets\.py)$
 pass_filenames: false

66 changes: 66 additions & 0 deletions
CLAUDE.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,6 +109,72 @@ rather than adding new standalone sections.
 - Update config rev
 - Commit config first

## Code Snippet System

`scripts/sync_snippets.py` replaces the content between
`<!-- snippet-source ... -->` / `<!-- /snippet-source -->` markers with code
from the referenced source file. The source file is the source of truth —
never edit synced content directly in the target.

To sync only part of a file, append `#RegionName` to the path. Regions are
delimited in source files by `# region Name` / `# endregion Name` markers.
Each example lives in a named function (returning `-> None`) wrapping a region.
Names follow `ClassName_methodName_variant` for methods, `functionName_variant`
for standalone functions, or `module_overview` for module docstrings. Pick a
descriptive variant suffix (`_basic`, `_sync`/`_async`, `_with_context`, etc.):

````python
def MyClass_do_thing_basic(obj: MyClass) -> None:
 # region MyClass_do_thing_basic
 result = obj.do_thing("arg")
 print(result)
 # endregion MyClass_do_thing_basic
````

Function parameters supply typed dependencies the example needs but does not create
(e.g., `server: MCPServer`); module-level stubs are only for truly undefined references
(e.g., `async def fetch_data() -> str: ...`).

NEVER put `# type: ignore`, `# pyright: ignore`, or `# noqa` inside a region — these
sync verbatim into the target. Restructure the code to address the errors instead.

After editing an example file, run `uv run --frozen pyright` to verify types, then
`uv run python scripts/sync_snippets.py` to sync. Use `--check` to verify without
modifying files.

### Markdown Code Examples

Code examples in `README.v2.md` and `docs/**/*.md` use explicit paths relative
to the repo root:

````markdown
<!-- snippet-source examples/snippets/servers/basic_tool.py -->
```python
# replaced by sync script
```
<!-- /snippet-source -->
````

### Docstring Code Examples

Code examples in `src/` docstrings use companion files in
`examples/snippets/docstrings/`, mirroring the source tree
(`src/mcp/foo/bar.py` → `examples/snippets/docstrings/mcp/foo/bar.py`).
Companion files are standalone scripts (not packages) starting with
`from __future__ import annotations`.

Docstrings use path-less `#Region` markers (only supported in `src/` files):

````text
 Example:
 <!-- snippet-source #MyClass_do_thing_basic -->
 ```python
 result = obj.do_thing("arg")
 print(result)
 ```
 <!-- /snippet-source -->
````

## Error Resolution

1. CI Failures
Expand Down

4 changes: 2 additions & 2 deletions
CONTRIBUTING.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -92,10 +92,10 @@ uv run ruff check .
uv run ruff format .
```

7. Update README snippets if you modified example code:
7. Update code example snippets if you modified example code:

```bash
uv run scripts/update_readme_snippets.py
uv run scripts/sync_snippets.py
```

8. (Optional) Run pre-commit hooks on all files:
Expand Down
Loading