ci: port docs example compilation check to all client languages - #243
ci: port docs example compilation check to all client languages#243harish18092002 wants to merge 2 commits into
Conversation
|
@harish18092002 Thanks for making this PR. Are you planning on implementing the checker for the other languages as well? |
No worries @Aryex Yeah sure |
…lize the same extract-and-validate flow to every GLIDE client language so broken snippets are caught in CI instead of by readers.
|
@Aryex Updated and added support for other languages |
|
Hey @harish18092002, thanks for taking the time to work on this! After looking at it more closely, I realized the original issue #237 wasn't clear enough. I've updated the descriptions with more contexts. In essence, our current C# example validator extracts the example codes into a C# project and compiles them. This not only catches syntax errors but also API mismatch, and we want to replicate this for other languages as well. I have opened #253 that implements the Node example validator. It should help illustrate the direction we're going. Feel free to take a look and leave some comments. That said, let me know if you'd like to continue working on this, or I can take it from here. Either way, appreciate the contribution 🙏 |
|
@harish18092002 Are you still working on this? Otherwise I will close the PR |
2 participants
Summary
Ports the existing C# documentation example compilation check to the other GLIDE client languages (Python, Go, Node, Java, PHP). It follows the exact same split design already used for C#: this
docs repo extracts the code snippets embedded in the docs, and each client repo's
validate_examples.pycompiles them. This catches broken/out-of-date code examples in CI instead of leavingthem for readers to hit.
Issue link
This Pull Request is linked to issue (URL): #243
Content Changes
No documentation pages were changed. This PR only adds tooling that validates the code examples already embedded in
src/content/docs/**/*.mdx.Implementation
Docs-repo half (this repo):
scripts/extract_examples.py— new shared, language-aware extractor (library + CLI). Pulls fenced code blocks for a language out of the MDX into a{"<file>:<line>": code}map. Generalizesthe previously C#-only extraction; verified byte-identical to the old csharp output (10 keys gain
+1on the line number because the old regex pointed at the blank line before the fence — thenew value is the fence line itself).
scripts/check_examples.py— new generic orchestrator: extracts a language's blocks, writes them to a temp JSON file, and hands them to that language's upstreamvalidate_examples.py,forwarding artifact args (e.g.
--glide-dll/--glide-jar). Supports--skip-if-no-validator.scripts/check_csharp_examples.py— refactored into a thin wrapper over the shared modules. Its CLI is unchanged, socheck-csharp-examples.ymlkeeps working as-is.scripts/README.md— documents the architecture and thevalidate_examples.pycontract each client repo must implement (input JSON format, args, exit codes, dedent responsibility,per-language status).
.github/workflows/check-{python,go,node,java,php}-examples.yml— one CI job per language. Each probes the upstream repo for itsvalidate_examples.py; until it lands, the job skips cleanly(green run + notice) and then enforces automatically once it exists.
Note for reviewers: the non-C# languages are intentionally inert until their upstream validator lands — this PR is the docs-repo half of the agreed split design.
Testing
python -m py_compile).csharp,java,python,go,node,php); errors cleanly on unknown languages.--skip-if-no-validator, missing-validator error, and C#-wrapper backward compatibility. Confirmed the exactargv forwarded to the validator (no leaked
--).scripts/README.mdare Prettier-clean (format:checkpasses).src/content/docs/, so the Astro site build and the rendered link set are unaffected.Checklist
Before submitting the PR make sure the following are checked:
--signoffflag.pnpm buildruns successfully.