feat: add tryitnow for usage snippets through code samples API #20

jagarnica · 2025-06-13T15:57:48Z

Resolve DOCS-5174

This PR fetches code samples for the code samples API to be used by the TryItNow editor in docs.

linear · 2025-06-13T16:12:16Z

DOCS-5174 Docs: Example Generation for TryItNow

Generate code samples for use in the try it now editor.

Requirements:

Code samples should be generally able to be run (there can be a few broken ones for now)
The snippets will be included during the docs generation step

Not required for now:

Intellisense for the types of the SDK (this will be added later)
Perfect sync between the sdk from the docs generation build SHA and the one published on npm
on-prem capabilities are deferred for now

nebrius · 2025-06-13T16:33:27Z

packages/docs-md/src/types/settings.ts


 export const settingsSchema = z.strictObject({
  spec: z.string(),
+  specFilename: z.string(),


We shouldn't add this here. This type specifically states what information should go in speakeasy.config.js, and I don't think we should require users to fill this in given that they already supplied this information on the line above.

Oooh thanks for the heads up. This was a mistake on my part. I don't want the user to supply this since its from the path to the spec. I mistakenly thought this was just a global state type.

nebrius · 2025-06-13T16:36:48Z

packages/docs-md/src/generator/docsData/getDocsData.ts

 export async function getDocsData(
-  specContents: string
+  specContents: string,
+  specFilename: string


Instead of passing it in here, we can instead replace the logic with:

const { spec } = getSettings(); const specFilename = basename(spec);

packages/docs-md/src/generator/docsData/getDocsData.ts

packages/docs-md/src/types/chunk.ts

packages/docs-md/src/types/global.d.ts

nebrius · 2025-06-13T17:11:14Z

packages/docs-md/src/generator/docsData/getDocsData.ts

  const go = new Go();
  const result = await WebAssembly.instantiate(wasmBuffer, go.importObject);
  void go.run(result.instance);
  const serializedDocsData = await SerializeDocsData(specContents);


Oh actually hang on, I just noticed we're now calling SerializeDocsData twice in this function. We shouldn't do that either, since again this function is expensive.

Instead, let's create a new top-level group of operations at src/generator/codeSnippets, and move all logic in there. Then, we call the top-level function (which takes in docs data) and returns code snippets, that we add between the getDocsData and generateContent functions in packages/docs-md/src/generator/generatePages.ts.

jagarnica · 2025-06-13T19:03:00Z

packages/docs-md/src/generator/mdx/renderer.ts

      ])
    );
-    this.#lines.push(`<TryItNow {...${JSON.stringify(escapedProps)}} />`);
+    this.#lines.push(`<TryItNow {...${JSON.stringify(escapedProps)}} externalDependencies={${JSON.stringify(props.externalDependencies)}} defaultValue={\`${props.defaultValue}\`} />`);


I noticed that if we escape these values, things don't render correctly and the dependencies can't be read for the TryItNow component. I think there is a fix somewhere else that would address this.

Yeah, escaping needs some love. I have some code in a branch somewhere that creates a much more robust escaping mechanism, but it's not quite ready yet.

jagarnica · 2025-06-13T19:58:45Z

packages/docs-md/assets/TryItNow/index.tsx

          ...sandpackSetupOptions,
        }}
-        theme="auto"
+        theme="dark"


Setting the default to dark for now due to an issue with the text color not changing when going from "light" mode to "dark" mode.

jagarnica · 2025-06-13T19:59:11Z

packages/docs-md/src/cli/cli.ts

  "-p": "--page-out-dir",
  "-o": "--component-out-dir",
  "-f": "--framework",
+  "-n": "--npm-package-name",


This sets the name of the npm package downloaded later in TryItNow

nebrius · 2025-06-13T20:21:46Z

packages/docs-md/src/cli/cli.ts

  "-p": "--page-out-dir",
  "-o": "--component-out-dir",
  "-f": "--framework",
+  "-n": "--npm-package-name",


Suggested change

"-n": "--npm-package-name",

Let's leave this flag out. Only about half of the settings are exposed by the CLI anyways, and I've been thinking about removing all but -c and -s anyways.

nebrius · 2025-06-13T20:26:09Z

packages/docs-md/src/generator/codeSnippets.ts

+const codeSnippets = new Map<string, CodeSnippet>();
+
+export function setCodeSnippet(snippet: CodeSnippet) {
+  codeSnippets.set(snippet.operationId, snippet);
+}
+
+export function getCodeSnippet(operationId: string) {
+  return codeSnippets.get(operationId);
+}


Suggested change

const codeSnippets = new Map<string, CodeSnippet>();

export function setCodeSnippet(snippet: CodeSnippet) {

codeSnippets.set(snippet.operationId, snippet);

}

export function getCodeSnippet(operationId: string) {

return codeSnippets.get(operationId);

}

Let's not do this style of storing for code snippets. I only did it for settings caused they're used everywhere, and even then I was on the fence and am kinda worried it's going to come back to bite me in the ass 😅 . We don't use this approach for docs data though, and I think we should be consistent how we access information about a spec throughout the codebase.

nebrius · 2025-06-13T20:27:17Z

packages/docs-md/src/generator/codeSnippets.ts

+  return (json as CodeSamplesResponse).snippets;
+}
+
+export const fetchAndStoreDocsCodeSnippets = async (


To follow up from the above, let's merge this in with fetchCodeSnippets so that fetchCodeSnippets takes in just two parameters: docsData and specContents (the other two can be fetched from getSettings())

nebrius

We'll follow up later with the issue of some methods having the wrong name.

* add basic piping for try it now * add npmPackageName as a string * remove type from global * clean up types, use separate state for usageSnippets * add optimization regarding chunks * move snippet logic to top-level function * set default theme to dark * formatting changes * move logic for CodeSnippets closer to rendering of data * remove flag for npm package * Fleshed out settings so that try-it-now is optional * Reverted SnippetAI formatting changes --------- Co-authored-by: nebrius <[email protected]>

nebrius reviewed Jun 13, 2025

View reviewed changes

packages/docs-md/src/generator/docsData/getDocsData.ts Outdated Show resolved Hide resolved

packages/docs-md/src/types/chunk.ts Outdated Show resolved Hide resolved

nebrius reviewed Jun 13, 2025

View reviewed changes

packages/docs-md/src/types/global.d.ts Outdated Show resolved Hide resolved

nebrius reviewed Jun 13, 2025

View reviewed changes

jagarnica commented Jun 13, 2025

View reviewed changes

jagarnica marked this pull request as ready for review June 13, 2025 20:02

nebrius reviewed Jun 13, 2025

View reviewed changes

jagarnica added 10 commits June 13, 2025 15:51

add basic piping for try it now

595e165

add npmPackageName as a string

8136687

remove type from global

9f84e59

clean up types, use separate state for usageSnippets

cbbce85

add optimization regarding chunks

8a62eb9

move snippet logic to top-level function

9ddf2fb

set default theme to dark

914c786

formatting changes

3d068e5

move logic for CodeSnippets closer to rendering of data

811f645

remove flag for npm package

67ef515

jagarnica force-pushed the feat/add-usage-snippets branch from 5abe295 to 67ef515 Compare June 13, 2025 22:52

nebrius added 2 commits June 13, 2025 16:10

Fleshed out settings so that try-it-now is optional

9d07a43

Reverted SnippetAI formatting changes

232a468

nebrius approved these changes Jun 13, 2025

View reviewed changes

jagarnica added this pull request to the merge queue Jun 13, 2025

Merged via the queue into main with commit 00107f8 Jun 13, 2025
1 check passed

feat: add tryitnow for usage snippets through code samples API #20

feat: add tryitnow for usage snippets through code samples API #20

Uh oh!

Conversation

jagarnica commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linear bot commented Jun 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nebrius Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nebrius left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jagarnica commented Jun 13, 2025 •

edited

Loading

nebrius Jun 13, 2025 •

edited

Loading