Move the code samples out of the markdown into snippet files - #2196
Move the code samples out of the markdown into snippet files#2196GWeale wants to merge 1 commit into
Conversation
Every fenced code block on the docs pages becomes a pymdownx.snippets include pointing at a file under examples/inline/, so the sample lives in a real file with a real extension rather than inside prose. The rendered site is unchanged. I built the site before and after and compared the output trees: all 808 pages, plus llms-full.txt and the generated per-page markdown, are byte identical. Tab structure and code fence rendering were compared page by page as well, since the strict build does not detect a code block that falls out of its tab. The link checker is widened to cover the new tree in the same change. It scans './**/*.md', so 126 URLs that currently sit inside fenced blocks would otherwise stop being checked the moment the code moved out of markdown. Go snippets are written with a .go.txt extension deliberately. gofmt runs over every changed *.go file and every *.go file under examples/go must appear in a build manifest, and a fragment lifted out of prose satisfies neither. The existing Go and Kotlin snippet guards still pass and no new *.go file is added. Snippet files end without a trailing newline, also deliberately: pymdownx.snippets appends an extra blank line for a file that ends in one, which renders as a stray line at the bottom of the block.
There was a problem hiding this comment.
We do not want to manage code snippets for integrations as separate files. Integrations are mostly contributed by third parties and we need to keep the authoring for them as simple as possible.
revert all the changes to the integrations/** pages and remove the separate code files
| @@ -0,0 +1,7 @@ | |||
| // Before (ADK Go 1.x) | |||
There was a problem hiding this comment.
GLOBAL: Revert all "*.txt" inclusions.
??? This".txt" file isn't even compilable code. If you are not actually going make the code runnable, then leave the code snippet in the page and don't pull it into a separate file. The net effect of ".txt" inclusions is to massively increase the maintenance costs of this content with zero benefit.
| agent_card="http://localhost:8000/a2a/remote_agent/.well-known/agent-card.json", | ||
| use_legacy=False, | ||
| ) | ||
| --8<-- "examples/inline/python/a2a/a2a-extension/001-client-side-extension-activation.py" |
There was a problem hiding this comment.
GLOBAL: Inclusions are not specific (global fix): In order to not bloat pages unnecessarily, the inclusions need to be targeted and not include the entirety of the source code file. You do this by inserting tags in the source code file to mark the beginning and ending of the code you want to include (and skip all the boilerplate stuff).
Not doing this will bloat the documentation pages with lines and lines boilerplate code and wind up frustrating users
There was a problem hiding this comment.
Is this TypeScript code actually compilable?
What is the benefit of having such a small amount of code stored separately like this?
| "google.golang.org/adk/v2/agent/llmagent" | ||
| ) | ||
|
|
||
| --8<-- "examples/go/snippets/agents/multi-agent/main.go:hierarchy" |
There was a problem hiding this comment.
Chaining includes makes this content significantly harder to maintain because now you have to follow the includes to update the whole code snippet. Can we make this simpler so code examples only have one file?
There was a problem hiding this comment.
What's showing up, here is that some pages, like custom-agents, probably have too many code snippets on them and those snippets need to be culled and simplified to reduce the maintenance cost and possibility of code errors.
|
|
||
| // After (ADK Go 2.0) | ||
| ev := session.NewEvent(ctx, ctx.InvocationID()) | ||
| --8<-- "examples/inline/go/2.0/index/002-event-construction-session-newevent-sign.go.txt" |
There was a problem hiding this comment.
similar comment here. too much for no appreciable gain, and added maintenance cost.
|
|
||
| // After (ADK TypeScript 2.0), outside an agent's own execution | ||
| const name = ctx.agent?.name; | ||
| --8<-- "examples/inline/typescript/2.0/index/001-context-invocationcontext-agent-is-optio.ts" |
There was a problem hiding this comment.
This change is complete overkill for 6 lines of code. Remove
3 participants
Every fenced code block on the docs pages becomes a
pymdownx.snippetsinclude pointing at a file under
examples/inline/, so each sample lives in areal file with a real extension instead of inside prose.
This is large and mechanical: 1,247 files, 23,308 added, 22,285 removed.
Almost all of it is the same code moving. The markdown loses 22,285 lines and
gains 1,065 pointer lines; those lines reappear as 1,063 new files. I would
understand a preference to take it in sections rather than at once, and I am
happy to split it that way — say the word and I will close this in favour of a
smaller proposal against one part of the tree.
The rendered site does not change
I built the site before and after and compared the output trees. All 808 pages
are byte identical, as are
llms-full.txtand the generated per-page markdown.I also compared tab structure and code fence rendering page by page, because
mkdocs build --strictdoes not detect a code block that has fallen out of itstab: an unindented line inside a
=== "Python"block closes the tab early andthe fence below renders as literal text, and the build still exits 0. That check
is what caught two such breaks while preparing this, so it is not hypothetical.
The link checker is widened in the same change
link-checker.yamlscans'./**/*.md'. 126 URLs currently sit inside fencedcode blocks, and they would silently stop being checked the moment the code left
markdown. The glob now also covers
./examples/inline/**.This is the one behavioural regression the move introduces, and fixing it here
rather than later seemed better than leaving it to be discovered by a dead link.
Two deliberate oddities
Go snippets use a
.go.txtextension.gofmtruns over every changed*.gofile, and every*.gounderexamples/gomust be registered in a buildmanifest. A fragment lifted out of prose satisfies neither. The existing Go and
Kotlin snippet guards still pass, and the change adds no new
*.gofile. Thecost is that these snippets stay invisible to Go tooling.
Snippet files end without a trailing newline.
pymdownx.snippetsappends anextra blank line for a file that ends in one, which renders as a stray line at
the bottom of every block. This is load-bearing: adding the conventional newline
changes two rendered pages. An
end-of-file-fixerhook would break the site.What I checked
names, no paths over 200 characters, all valid UTF-8.
check_paths: trueis already set, so a missing snippet is a hard buildfailure rather than a silently empty code block.
Known gaps
examples/pythonfiles have them. Whole-file includes mean a header wouldrender into the page. Getting both needs
[start:]/[end:]section markerson every file, which is a meaningfully larger change. I can do it if you want
it before this lands.
docs/integrations/application-integration.mdis skipped: itsfence opens at six spaces and closes at eight, so it never terminates. Fix code samples that do not compile against the shipped SDKs #2194
fixes that fence; once it lands this can pick up the block.
second needs a rebase, and I am happy to do it.