Extract code examples to generated documentation files - #1350
Merged
Conversation
…actor The code examples added in the recent documentation update were inline in the mdx files. This moves them alongside the tests of the language DSLs, marked with example-extractor comments, so they are compiled (and therefore stay correct) and are presented in both Typescript and Java: - Function call definition (caller and implementer side, including the throwing variants) in both DSLs - HTTP server-driven contract definition (mockConfig, interactions, and state handlers), now with Java examples - Function registration during verification, including the Java JSON marshaller adapters - Trigger groups for HTTP client verification (TriggerGroupMap / TriggerGroups), now with Java examples Also regenerates the previously-stale extracted examples, and fixes a broken link in the http-server chapter that failed the docusaurus build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SoNKMWGAeFzwTQZA5XUhsr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR refactors documentation examples by extracting code snippets from test files into separate generated markdown files. This allows the same code examples to be reused across multiple documentation pages while maintaining a single source of truth.
Key Changes
New test files with extractable examples: Added documentation test files for both TypeScript/Jest and Java that contain code examples marked with
example-extractandignore-extractcomments:defining-a-server-contract.spec-norun.ts- HTTP server contract examplesdefining-a-function-contract.spec-norun.ts- Function caller examplesdefining-a-function-contract-throwing.spec-norun.ts- Throwing function examplesreceiving-function-calls.spec-norun.ts- Function receiver examplesreceiving-function-calls-throwing.spec-norun.ts- Throwing function receiver examplesregistering-functions.spec-norun.ts- Function registration examplesverifying-with-triggers.spec-norun.ts- Verification trigger examplesdsl-java/src/test/java/Generated example markdown files: Created
.mdxfiles inpackages/documentation/docs/examples/generated/for each extracted code example:_http-server-config.ts.mdxand.java.mdx_http-server-state-handlers.ts.mdxand.java.mdx_http-server-interactions.ts.mdxand.java.mdx_function-caller-define.ts.mdxand.java.mdx_function-caller-throwing.ts.mdxand.java.mdx_function-receiver-define.ts.mdxand.java.mdx_function-receiver-throwing.ts.mdxand.java.mdx_function-receiver-marshaller.java.mdx_verify-trigger-groups.ts.mdxand.java.mdx_verify-trigger-state-variables.ts.mdxand.java.mdx_verify-register-functions.ts.mdxand.java.mdx_verify-register-marshaller.java.mdxUpdated documentation pages: Modified documentation files to import and display the generated examples using Tabs components for language selection:
defining-contracts/http-server/defining-example.mdxdefining-contracts/function-calls/defining-example.mdxdefining-contracts/function-calls/receiving-function-calls.mdxverifying-contracts/http-client/triggers.mdxverifying-contracts/function-execution/registering-functions.mdxUpdated helper files: Modified
YourApi.tsto add ahealth()method stub for trigger examplesImplementation Details
// example-extract _example-nameand// end-examplecomments// ignore-extractand// end-ignorecomments.mdxfiles contain code blocks extracted from the test fileshttps://claude.ai/code/session_01SoNKMWGAeFzwTQZA5XUhsr