diff --git a/apps/docs-generator/project.json b/apps/docs-generator/project.json index 45085706f..a8beaaf6b 100644 --- a/apps/docs-generator/project.json +++ b/apps/docs-generator/project.json @@ -13,11 +13,11 @@ } }, "start": { - "executor": "@nx/js:node", - "dependsOn": ["generate-language-server"], + "executor": "nx:run-commands", + "dependsOn": ["generate-language-server", "build"], "options": { - "watch": false, - "buildTarget": "docs-generator:build" + "commands": ["node dist/apps/docs-generator/main.js"], + "parallel": false } }, "generate-language-server": { diff --git a/apps/docs-generator/src/main.ts b/apps/docs-generator/src/main.ts index 4126bcfd6..ae8a8e380 100644 --- a/apps/docs-generator/src/main.ts +++ b/apps/docs-generator/src/main.ts @@ -131,4 +131,6 @@ ${exampleModel.toString()} main() .then(() => console.log('Finished generating docs!')) - .catch((e) => console.error(e)); + .catch((e) => { + throw e; + }); diff --git a/apps/docs-generator/src/user-doc-generator.ts b/apps/docs-generator/src/user-doc-generator.ts index 0263d851e..a7dcaddc7 100644 --- a/apps/docs-generator/src/user-doc-generator.ts +++ b/apps/docs-generator/src/user-doc-generator.ts @@ -38,30 +38,15 @@ that fullfil [_constraints_](./primitive-value-types#constraints).`.trim(), valueTypes .filter((valueType) => valueType.isReferenceableByUser()) .forEach((valueType) => { + const description = valueType.getUserDocDescription(); assert( - valueType.getUserDoc() !== undefined, + description !== undefined, `Documentation is missing for user extendable value type: ${valueType.getName()}`, ); builder .heading(valueType.getName(), 2) - .description(valueType.getUserDoc() ?? '', 3) - .examples( - [ - { - code: ` -block ExampleTableInterpreter oftype TableInterpreter { - header: true; - columns: [ - "columnName" oftype ${valueType.getName()} - ]; -}`.trim(), - description: `A block of type \`TableInterpreter\` that - interprets data in the column \`columnName\` as \`${valueType.getName()}\`. - `.trim(), - }, - ], - 3, - ); + .description(description, 3) + .examples(valueType.getUserDocExamples(), 3); }); return builder.build(); @@ -109,7 +94,7 @@ block ExampleTableInterpreter oftype TableInterpreter { return builder.build(); } - private extractDocsFromComment(comment?: string | undefined): + private extractDocsFromComment(comment?: string): | { description: string | undefined; examples: ExampleDoc[]; diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts index 911b2c403..66cb00671 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/boolean-value-type.ts @@ -36,7 +36,7 @@ export class BooleanValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` A boolean value. Examples: true, false diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts index 05090e709..68d3f2690 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/decimal-value-type.ts @@ -43,7 +43,7 @@ export class DecimalValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` A decimal value. Example: 3.14 diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts index 531b17600..53ddd0cd1 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/integer-value-type.ts @@ -39,7 +39,7 @@ export class IntegerValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` An integer value. Example: 3 diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts index 818dc657b..0b0c57ff2 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/primitive-value-type.ts @@ -8,6 +8,7 @@ import { } from '../../../expressions/internal-value-representation'; import { AbstractValueType } from '../abstract-value-type'; import { type ValueType } from '../value-type'; +import { type ExampleDoc } from '../../typed-object/typed-object-wrapper'; export abstract class PrimitiveValueType< I extends InternalValidValueRepresentation = InternalValidValueRepresentation, @@ -33,10 +34,39 @@ export abstract class PrimitiveValueType< * Text only, no comment characters. * Should be given for all user-referenceable value types {@link isReferenceableByUser} */ - getUserDoc(): string | undefined { + getUserDocDescription(): string | undefined { return undefined; } + getUserDocExamples(): ExampleDoc[] { + const name = this.getName(); + const capitalizedName = name.charAt(0).toUpperCase() + name.slice(1); + return [ + { + code: ` +valuetype TableSchema { + tableColumn: ${name}; +} +transfrom tableRowParser { + from r oftype SheetRow; + to tableRow oftye TableSchema; + + tableRow: { + tableColumn: as${capitalizedName} (r . "tableColumn"); + }; +} +block ExampleTableInterpreter oftype TableInterpreter { + header: true; + columns: TableSchema; + parseWith: tableRowParser; +}`.trim(), + description: + `A block of type \`TableInterpreter\` that interprets data in the column "columnName" as \`${name}\`. + `.trim(), + }, + ]; + } + // eslint-disable-next-line @typescript-eslint/no-unused-vars fromString(_s: string): I | InvalidValue { return new InvalidValue(`Cannot parse ${this.getName()}`); diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts index 84cdee0bf..e89c5085e 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/sheetrow-value-type.ts @@ -5,6 +5,7 @@ import { PrimitiveValueType } from './primitive-value-type'; import { type ValueTypeVisitor } from '../value-type'; import { type InternalValidValueRepresentation } from '../../../expressions'; +import { type ExampleDoc } from '../../typed-object/typed-object-wrapper'; export class SheetRowValueType extends PrimitiveValueType { acceptVisitor(visitor: ValueTypeVisitor): R { @@ -19,6 +20,41 @@ export class SheetRowValueType extends PrimitiveValueType { return 'SheetRow'; } + override getUserDocDescription(): string { + return ` +The values of a row inside a sheet. Only usable inside a transform that parses SheetRows into a value type. +Accessible via the dot operator (see example). +`.trim(); + } + + override getUserDocExamples(): ExampleDoc[] { + return [ + { + code: ` +valuetype Coordinate { + x: decimal; + y: decimal; +} +transfrom coordinateParser { + from r oftype SheetRow; + to coord oftye Coordinate; + + coord: { + x: asDecimal (r . "x"); + y: asDecimal (r . 1); + }; +} +block ExampleTableInterpreter oftype TableInterpreter { + header: true; + columns: Coordinate; + parseWith: CoordinateParser; +}`.trim(), + description: + 'A transform, used in a block of type `TableInterpreter`, that interprets a `SheetRow` into a table row with columns `x` and `y`.', + }, + ]; + } + override isInternalValidValueRepresentation( operandValue: InternalValidValueRepresentation, ): operandValue is string[] { diff --git a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts index e7010c752..c80896f16 100644 --- a/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts +++ b/libs/language-server/src/lib/ast/wrappers/value-type/primitive/text-value-type.ts @@ -30,9 +30,9 @@ export class TextValuetype extends PrimitiveValueType { return true; } - override getUserDoc(): string { + override getUserDocDescription(): string { return ` -A text value. +A text value. Example: "Hello World" `.trim(); } diff --git a/libs/language-server/src/lib/workspace/stdlib.ts b/libs/language-server/src/lib/workspace/stdlib.ts index 375259d01..14fd518f5 100644 --- a/libs/language-server/src/lib/workspace/stdlib.ts +++ b/libs/language-server/src/lib/workspace/stdlib.ts @@ -39,7 +39,7 @@ export function getStdLib() { function parseBuiltinValuetypeToJayvee(valueType: PrimitiveValueType): string { const lines: string[] = []; - const userDoc = valueType.getUserDoc(); + const userDoc = valueType.getUserDocDescription(); if (userDoc !== undefined) { lines.push(parseAsComment(userDoc)); } diff --git a/package.json b/package.json index 0f2cdcd7b..c06b1bd27 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,8 @@ "example:gtfs": "nx run interpreter:run -d example/gtfs-static.jv -dg peek", "example:gtfs-rt": "nx run interpreter:run -d example/gtfs-rt.jv -dg peek", "example:workbooks": "nx run interpreter:run -d example/workbooks-xlsx.jv -dg peek", - "example:vehicles": "nx run interpreter:run -d -e DB_HOST=localhost -e DB_PORT=5432 -e DB_USERNAME=postgres -e DB_PASSWORD=postgres -e DB_DATABASE=postgres example/electric-vehicles.jv -dg peek" + "example:vehicles": "nx run interpreter:run -d -e DB_HOST=localhost -e DB_PORT=5432 -e DB_USERNAME=postgres -e DB_PASSWORD=postgres -e DB_DATABASE=postgres example/electric-vehicles.jv -dg peek", + "clean": "nx reset && rm -r dist/ tmp/ apps/vs-code-extension/assets/jayvee.tmLanguage.json apps/docs/docs/user/block-types/**/*.md apps/docs/docs/user/value-types/built-in-value-types.md apps/docs/docs/user/examples/*.md apps/docs/src/theme/prism-jayvee.js libs/language-server/src/lib/*/generated libs/monaco-editor/src/lib/{language-configuration,jayvee.tmLanguage}.json" }, "private": true, "dependencies": {