docs: add WorkflowReadableStreamOptions to start api reference #100
Conversation
🦋 Changeset detectedLatest commit: 2771d16 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
| #### WorkflowReadableStreamOptions | ||
|
|
||
| <TSDoc | ||
| definition={generateDefinition({ | ||
| code: ` | ||
| import type { WorkflowReadableStreamOptions } from 'workflow/api'; | ||
| export default WorkflowReadableStreamOptions;` | ||
| })} | ||
| /> |
There was a problem hiding this comment.
The WorkflowReadableStreamOptions documentation section is incorrectly placed under the "Returns" section, but it's not actually a return type of start(). It's a parameter type for the Run.getReadable() method, so it should be documented elsewhere or repositioned.
View Details
📝 Patch Details
diff --git a/docs/content/docs/api-reference/workflow-api/start.mdx b/docs/content/docs/api-reference/workflow-api/start.mdx
index 62de19f..72a339d 100644
--- a/docs/content/docs/api-reference/workflow-api/start.mdx
+++ b/docs/content/docs/api-reference/workflow-api/start.mdx
@@ -51,16 +51,6 @@ export default Run;`
showSections={['returns']}
/>
-#### WorkflowReadableStreamOptions
-
-<TSDoc
-definition={generateDefinition({
- code: `
-import type { WorkflowReadableStreamOptions } from 'workflow/api';
-export default WorkflowReadableStreamOptions;`
-})}
-/>
-
## Good to Know
* The `start()` function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
@@ -89,3 +79,17 @@ const run = await start(myWorkflow, ['arg1', 'arg2'], { // [!code highlight]
deploymentId: 'custom-deployment-id' // [!code highlight]
}); // [!code highlight]
```
+
+## Type Reference
+
+### WorkflowReadableStreamOptions
+
+Used when calling [`Run.getReadable()`](/docs/api-reference/workflow-api/start#getReadable) on the returned `Run` object to configure the readable stream:
+
+<TSDoc
+definition={generateDefinition({
+ code: `
+import type { WorkflowReadableStreamOptions } from 'workflow/api';
+export default WorkflowReadableStreamOptions;`
+})}
+/>
Analysis
Incorrectly placed WorkflowReadableStreamOptions documentation under Returns section
What fails: Documentation for WorkflowReadableStreamOptions is placed under the "Returns" section of start() function documentation, implying it's a return type of start(), when it's actually a parameter type for Run.getReadable(options: WorkflowReadableStreamOptions)
How to reproduce:
- Navigate to docs/content/docs/api-reference/workflow-api/start.mdx
- View the documentation -
WorkflowReadableStreamOptionsis listed under "Returns" after theRunclass documentation - This suggests to developers that
WorkflowReadableStreamOptionsis returned bystart(), which is incorrect
Current behavior: start() returns a Run object. The WorkflowReadableStreamOptions type is only used as a parameter when calling the Run.getReadable() method, not as a return type.
Expected behavior: Documentation should make clear that WorkflowReadableStreamOptions is a parameter type for Run methods, not a return type of start(). Moved documentation to new "Type Reference" section after examples to clarify its relationship to the Run.getReadable() method.
Fix: Removed WorkflowReadableStreamOptions from the Returns section and added it to a new "Type Reference" section at the end of the documentation with clarification that it's used when calling Run.getReadable().
There was a problem hiding this comment.
🔧 Build Fix:
The link validation script fails because a relative URL ./get-run#workflowreadablestreamoptions is used instead of the expected absolute path format /docs/api-reference/workflow-api/get-run#workflowreadablestreamoptions.
View Details
📝 Patch Details
diff --git a/docs/content/docs/api-reference/workflow-api/start.mdx b/docs/content/docs/api-reference/workflow-api/start.mdx
index 5e294cb..aab8121 100644
--- a/docs/content/docs/api-reference/workflow-api/start.mdx
+++ b/docs/content/docs/api-reference/workflow-api/start.mdx
@@ -51,7 +51,7 @@ export default Run;`
showSections={['returns']}
/>
-Learn more about [`WorkflowReadableStreamOptions`](./get-run#workflowreadablestreamoptions).
+Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-api/get-run#workflowreadablestreamoptions).
## Good to Know
Analysis
Link validation failure in MDX documentation
What fails: The docs package postinstall script fails during link validation due to a relative URL in content/docs/api-reference/workflow-api/start.mdx
How to reproduce:
pnpm installResult:
docs postinstall: Invalid URLs in content/docs/api-reference/workflow-api/start.mdx:
docs postinstall: ./get-run#workflowreadablestreamoptions: relative URL ./get-run detected, but 'baseUrl' option is missing. at line 54 column 18
docs postinstall: ------
docs postinstall: 1 errored file, 1 errors
docs postinstall: Failed
ELIFECYCLE Command failed with exit code 1.
There was a problem hiding this comment.
🔧 Build Fix:
The link validation script is missing baseUrl configuration and file URL information needed to resolve relative links, causing the build to fail during the docs postinstall step.
View Details
📝 Patch Details
diff --git a/docs/scripts/lint.ts b/docs/scripts/lint.ts
index 9f2adfe..96963db 100644
--- a/docs/scripts/lint.ts
+++ b/docs/scripts/lint.ts
@@ -12,14 +12,22 @@ async function checkLinks() {
// we read them all at once to avoid repeated file read
const docsFiles = await readFiles('content/docs/**/*.{md,mdx}');
+ // Add URL to each file for relative link resolution
+ docsFiles.forEach((file) => {
+ const info = parseFilePath(path.relative('content/docs', file.path));
+ const slugs = getSlugs(info);
+ file.url = '/docs/' + slugs.join('/');
+ });
+
const scanned = await scanURLs({
populate: {
'docs/[[...slug]]': docsFiles.map((file) => {
const info = parseFilePath(path.relative('content/docs', file.path));
+ const toc = getTableOfContents(file.content);
return {
value: getSlugs(info),
- hashes: getTableOfContents(file.content).map((item) =>
+ hashes: toc.map((item) =>
item.url.slice(1)
),
};
@@ -30,6 +38,7 @@ async function checkLinks() {
printErrors(
await validateFiles(docsFiles, {
scanned,
+ baseUrl: '/docs',
}),
true
);
Analysis
Link validation fails during docs postinstall script
What fails: The next-validate-link library in docs/scripts/lint.ts fails to validate relative URLs due to missing configuration for relative link resolution
How to reproduce:
pnpm installResult:
docs postinstall: Invalid URLs in content/docs/api-reference/workflow-api/start.mdx:
docs postinstall: ./get-run#workflowreadablestreamoptions: relative URL ./get-run detected, but 'baseUrl' option is missing. at line 54 column 18
docs postinstall: Failed
ELIFECYCLE Command failed with exit code 1.
There was a problem hiding this comment.
🔧 Build Fix:
The link validation script is missing the pathToUrl configuration needed for next-validate-link to properly resolve relative URLs in MDX files, causing the build to fail during the postinstall step.
View Details
📝 Patch Details
diff --git a/docs/scripts/lint.ts b/docs/scripts/lint.ts
index 9f2adfe..b02f220 100644
--- a/docs/scripts/lint.ts
+++ b/docs/scripts/lint.ts
@@ -9,8 +9,17 @@ import {
} from 'next-validate-link';
async function checkLinks() {
+ // Define pathToUrl function to convert file paths to URLs
+ const pathToUrl = (filePath) => {
+ const info = parseFilePath(path.relative('content/docs', filePath));
+ const slugs = getSlugs(info);
+ return '/docs/' + slugs.join('/');
+ };
+
// we read them all at once to avoid repeated file read
- const docsFiles = await readFiles('content/docs/**/*.{md,mdx}');
+ const docsFiles = await readFiles('content/docs/**/*.{md,mdx}', {
+ pathToUrl,
+ });
const scanned = await scanURLs({
populate: {
@@ -30,6 +39,7 @@ async function checkLinks() {
printErrors(
await validateFiles(docsFiles, {
scanned,
+ baseUrl: '/docs',
}),
true
);
Analysis
Link validation fails during pnpm install postinstall step
What fails: The next-validate-link library fails to validate relative URLs in MDX content because it lacks the pathToUrl configuration needed for relative URL resolution
How to reproduce:
cd docs && pnpm installResult:
. postinstall: Invalid URLs in content/docs/api-reference/workflow-api/start.mdx:
. postinstall: ./get-run#workflowreadablestreamoptions: relative URL ./get-run detected, but 'baseUrl' option is missing. at line 54 column 18
. postinstall: ------
. postinstall: 1 errored file, 1 errors
. postinstall: Failed
docs were missing
WorkflowReadableStreamOptionsin start page.also export type
WorkflowReadableStreamOptionsfromworkflow/api