From a5fc253410ca9b81491714b30069b2874550fda7 Mon Sep 17 00:00:00 2001 From: Travis Prescott Date: Mon, 25 Sep 2023 09:50:32 -0700 Subject: [PATCH] Core documentation - generate data type docs programmatically (#2467) Fixes #2297. --- .prettierignore | 2 + docs/standard-library/built-in-data-types.md | 410 +++++++++++++++++- .../tspd/src/ref-doc/emitters/docusaurus.ts | 13 +- .../website/.scripts/regen-compiler-docs.mjs | 4 + 4 files changed, 426 insertions(+), 3 deletions(-) diff --git a/.prettierignore b/.prettierignore index 1c75f4825..824a4a40e 100644 --- a/.prettierignore +++ b/.prettierignore @@ -34,8 +34,10 @@ spec.emu.html # Auto generated reference docs. docs/**/reference/ docs/standard-library/built-in-decorators.md +docs/standard-library/built-in-data-types.md packages/website/versioned_docs/**/reference/ packages/website/versioned_docs/**/standard-library/built-in-decorators.md +packages/website/versioned_docs/**/standard-library/built-in-data-types.md #.tsp init template eng/feeds/ diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index 6e0a469f9..9badf3d43 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -3,5 +3,413 @@ title: "Built-in Data types" toc_min_heading_level: 2 toc_max_heading_level: 3 --- +# Data types +## TypeSpec +### `Array` {#Array} + + + + +```typespec +model Array +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | The type of the array elements | + + + +### `DefaultKeyVisibility` {#DefaultKeyVisibility} + +Applies a visibility setting to a collection of properties. + +```typespec +model DefaultKeyVisibility +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | An object whose properties are spread. | +| Visibility | The visibility to apply to all properties. | + + + +### `object` {#object} + +Represent a model + +```typespec +model object +``` + + + +### `OmitDefaults` {#OmitDefaults} + +Represents a collection of properties with default values omitted. + +```typespec +model OmitDefaults +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | An object whose spread property defaults are all omitted. | + + + +### `OmitProperties` {#OmitProperties} + +Represents a collection of omitted properties. + +```typespec +model OmitProperties +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | An object whose properties are spread. | +| TKeys | The property keys to omit. | + + + +### `OptionalProperties` {#OptionalProperties} + +Represents a collection of optional properties. + +```typespec +model OptionalProperties +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | An object whose spread properties are all optional. | + + + +### `Record` {#Record} + + + + +```typespec +model Record +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | The type of the properties | + + + +### `ServiceOptions` {#ServiceOptions} + +Service options. + +```typespec +model ServiceOptions +``` + + + +### `UpdateableProperties` {#UpdateableProperties} + +Represents a collection of updateable properties. + +```typespec +model UpdateableProperties +``` + +#### Template Parameters +| Name | Description | +|------|-------------| +| T | An object whose spread properties are all updateable. | + + + +### `BytesKnownEncoding` {#BytesKnownEncoding} + +Known encoding to use on bytes + +```typespec +enum BytesKnownEncoding +``` + + + +### `DateTimeKnownEncoding` {#DateTimeKnownEncoding} + +Known encoding to use on utcDateTime or offsetDateTime + +```typespec +enum DateTimeKnownEncoding +``` + + + +### `DurationKnownEncoding` {#DurationKnownEncoding} + +Known encoding to use on duration + +```typespec +enum DurationKnownEncoding +``` + + + +### `boolean` {#boolean} + +Boolean with `true` and `false` values. + +```typespec +scalar boolean +``` + + + +### `bytes` {#bytes} + +Represent a byte array + +```typespec +scalar bytes +``` + + + +### `decimal` {#decimal} + +A decimal number with any length and precision. + +```typespec +scalar decimal +``` + + + +### `decimal128` {#decimal128} + +A 128-bit decimal number. + +```typespec +scalar decimal128 +``` + + + +### `duration` {#duration} + +A duration/time period. e.g 5s, 10h + +```typespec +scalar duration +``` + + + +### `float` {#float} + +A number with decimal value + +```typespec +scalar float +``` + + + +### `float32` {#float32} + +A 32 bit floating point number. (`±5.0 × 10^−324` to `±1.7 × 10^308`) + +```typespec +scalar float32 +``` + + + +### `float64` {#float64} + +A 32 bit floating point number. (`±1.5 x 10^−45` to `±3.4 x 10^38`) + +```typespec +scalar float64 +``` + + + +### `int16` {#int16} + +A 16-bit integer. (`-32,768` to `32,767`) + +```typespec +scalar int16 +``` + + + +### `int32` {#int32} + +A 32-bit integer. (`-2,147,483,648` to `2,147,483,647`) + +```typespec +scalar int32 +``` + + + +### `int64` {#int64} + +A 64-bit integer. (`-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`) + +```typespec +scalar int64 +``` + + + +### `int8` {#int8} + +A 8-bit integer. (`-128` to `127`) + +```typespec +scalar int8 +``` + + + +### `integer` {#integer} + +A whole number + +```typespec +scalar integer +``` + + + +### `numeric` {#numeric} + +A numeric type + +```typespec +scalar numeric +``` + + + +### `offsetDateTime` {#offsetDateTime} + +A date and time in a particular time zone, e.g. "April 10th at 3:00am in PST" + +```typespec +scalar offsetDateTime +``` + + + +### `plainDate` {#plainDate} + +A date on a calendar without a time zone, e.g. "April 10th" + +```typespec +scalar plainDate +``` + + + +### `plainTime` {#plainTime} + +A time on a clock without a time zone, e.g. "3:00 am" + +```typespec +scalar plainTime +``` + + + +### `safeint` {#safeint} + +An integer that can be serialized to JSON (`−9007199254740991 (−(2^53 − 1))` to `9007199254740991 (2^53 − 1)` ) + +```typespec +scalar safeint +``` + + + +### `string` {#string} + +A sequence of textual characters. + +```typespec +scalar string +``` + + + +### `uint16` {#uint16} + +A 16-bit unsigned integer (`0` to `65,535`) + +```typespec +scalar uint16 +``` + + + +### `uint32` {#uint32} + +A 32-bit unsigned integer (`0` to `4,294,967,295`) + +```typespec +scalar uint32 +``` + + + +### `uint64` {#uint64} + +A 64-bit unsigned integer (`0` to `18,446,744,073,709,551,615`) + +```typespec +scalar uint64 +``` + + + +### `uint8` {#uint8} + +A 8-bit unsigned integer (`0` to `255`) + +```typespec +scalar uint8 +``` + + + +### `url` {#url} + +Represent a URL string as described by https://url.spec.whatwg.org/ + +```typespec +scalar url +``` + + + +### `utcDateTime` {#utcDateTime} + +An instant in coordinated universal time (UTC)" + +```typespec +scalar utcDateTime +``` + -See [Language Basics: Built-in types](../language-basics/built-in-types) diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index 5e9075711..92784d050 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -159,13 +159,22 @@ function renderInterfacesFile( return renderMarkdowDoc(content); } -function renderDataTypes(renderer: DocusaurusRenderer, refDoc: TypeSpecRefDoc): string | undefined { +export type DataTypeRenderOptions = { + title?: string; +}; + +export function renderDataTypes( + renderer: DocusaurusRenderer, + refDoc: TypeSpecRefDoc, + options?: DataTypeRenderOptions +): string | undefined { if (!refDoc.namespaces.some((x) => x.models.length > 0)) { return undefined; } + const title = options?.title ?? "Data types"; const content: MarkdownDoc = [ "---", - `title: "Data types"`, + `title: "${title}"`, "toc_min_heading_level: 2", "toc_max_heading_level: 3", "---", diff --git a/packages/website/.scripts/regen-compiler-docs.mjs b/packages/website/.scripts/regen-compiler-docs.mjs index da47d068f..8d051d898 100644 --- a/packages/website/.scripts/regen-compiler-docs.mjs +++ b/packages/website/.scripts/regen-compiler-docs.mjs @@ -4,6 +4,7 @@ import { NodeHost, joinPaths, logDiagnostics } from "@typespec/compiler"; import { generateJsApiDocs, resolveLibraryRefDocsBase } from "@typespec/tspd/ref-doc"; import { DocusaurusRenderer, + renderDataTypes, renderDecoratorFile, } from "@typespec/tspd/ref-doc/emitters/docusaurus"; @@ -44,6 +45,9 @@ async function generateCompilerDocs() { const decoratorContent = renderDecoratorFile(renderer, refDoc, { title: "Built-in Decorators" }); assert(decoratorContent, "Unexpected decorator file shouldn't be empty for compiler."); await writeFile(join(outputDir, "built-in-decorators.md"), decoratorContent); + const dataTypeContent = renderDataTypes(renderer, refDoc, { title: "Built-in Data types" }); + assert(dataTypeContent, "Unexpected data type file shouldn't be empty for compiler."); + await writeFile(join(outputDir, "built-in-data-types.md"), dataTypeContent); await generateJsApiDocs(joinPaths(compilerPath), join(outputDir, "reference/js-api")); return diagnostics;