diff --git a/docs/emitters/json-schema/guide.md b/docs/emitters/json-schema/guide.md index 6636c477a..de277af1c 100644 --- a/docs/emitters/json-schema/guide.md +++ b/docs/emitters/json-schema/guide.md @@ -2,8 +2,6 @@ title: Guide --- -# JSON Schema files and references - When a TypeSpec data type has the `@jsonSchema` decorator or is declared inside a namespace with that decorator, it is considered a _JSON Schema type_. By default, this emitter will produce one JSON Schema file per JSON Schema type. The file defines an `$id` metadata keyword based on the TypeSpec type name and the file format of the schema (for example, `Widget.yaml`). The `$id` can be overridden by using the `@id` decorator. diff --git a/docs/emitters/json-schema/reference/data-types.md b/docs/emitters/json-schema/reference/data-types.md index 00d426ca0..27a1a59fb 100644 --- a/docs/emitters/json-schema/reference/data-types.md +++ b/docs/emitters/json-schema/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.JsonSchema ### `Json` {#TypeSpec.JsonSchema.Json} diff --git a/docs/emitters/json-schema/reference/decorators.md b/docs/emitters/json-schema/reference/decorators.md index 2d7f756e4..fc67e9a52 100644 --- a/docs/emitters/json-schema/reference/decorators.md +++ b/docs/emitters/json-schema/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.JsonSchema ### `@baseUri` {#@TypeSpec.JsonSchema.baseUri} diff --git a/docs/emitters/json-schema/reference/emitter.md b/docs/emitters/json-schema/reference/emitter.md index fad990667..fccf19c6f 100644 --- a/docs/emitters/json-schema/reference/emitter.md +++ b/docs/emitters/json-schema/reference/emitter.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Emitter - ## Usage 1. Via the command line diff --git a/docs/emitters/json-schema/reference/index.mdx b/docs/emitters/json-schema/reference/index.mdx index ce0f343fb..13d448cb9 100644 --- a/docs/emitters/json-schema/reference/index.mdx +++ b/docs/emitters/json-schema/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec ## Install diff --git a/docs/emitters/openapi3/cli.md b/docs/emitters/openapi3/cli.md index 3f8beaefe..2629af830 100644 --- a/docs/emitters/openapi3/cli.md +++ b/docs/emitters/openapi3/cli.md @@ -2,8 +2,6 @@ title: OpenAPI3 to TypeSpec --- -# tsp-openapi3 CLI - :::warning The OpenAPI3 to TypeSpec conversion purpose is a one time conversion to help you get started with TypeSpec. The output can change in future versions of TypeSpec without being considered a breaking change. diff --git a/docs/emitters/openapi3/diagnostics.md b/docs/emitters/openapi3/diagnostics.md index 847b7ef8a..af1aae874 100644 --- a/docs/emitters/openapi3/diagnostics.md +++ b/docs/emitters/openapi3/diagnostics.md @@ -2,8 +2,6 @@ title: Diagnostics --- -# Diagnostics - The OpenAPI emitter may produce any of the following diagnostic messages. diff --git a/docs/emitters/openapi3/openapi.md b/docs/emitters/openapi3/openapi.md index 1a04c8b79..b3a835883 100644 --- a/docs/emitters/openapi3/openapi.md +++ b/docs/emitters/openapi3/openapi.md @@ -2,8 +2,6 @@ title: Emitter operation --- -# Exploring the Functionality of the OpenAPI Emitter - The OpenAPI emitter is designed to translate TypeSpec language elements into their corresponding OpenAPI expressions. Here's how it works: ## Server Details diff --git a/docs/emitters/openapi3/reference/decorators.md b/docs/emitters/openapi3/reference/decorators.md index c377176b7..c057a1ad5 100644 --- a/docs/emitters/openapi3/reference/decorators.md +++ b/docs/emitters/openapi3/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.OpenAPI ### `@oneOf` {#@TypeSpec.OpenAPI.oneOf} diff --git a/docs/emitters/openapi3/reference/emitter.md b/docs/emitters/openapi3/reference/emitter.md index 53827c1e3..7b2816e70 100644 --- a/docs/emitters/openapi3/reference/emitter.md +++ b/docs/emitters/openapi3/reference/emitter.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Emitter - ## Usage 1. Via the command line diff --git a/docs/emitters/openapi3/reference/index.mdx b/docs/emitters/openapi3/reference/index.mdx index 63b200c63..b1836a03f 100644 --- a/docs/emitters/openapi3/reference/index.mdx +++ b/docs/emitters/openapi3/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec ## Install diff --git a/docs/emitters/protobuf/guide.md b/docs/emitters/protobuf/guide.md index b2a01305a..a02299cd7 100644 --- a/docs/emitters/protobuf/guide.md +++ b/docs/emitters/protobuf/guide.md @@ -2,8 +2,6 @@ title: Guide --- -# Understanding the Protobuf Emitter - TypeSpec includes a built-in emitter (`/protobuf`) that can generate Protocol Buffers specifications from TypeSpec sources. The Protobuf files generated can then be used to create gRPC services or any other tools that are compatible with Protocol Buffers. **Please note**: The Protobuf emitter is designed to work with Protocol Buffers 3 (proto3) syntax. Ensure that your workflow (including `protoc` version) supports proto3 to make full use of this emitter. diff --git a/docs/emitters/protobuf/reference/data-types.md b/docs/emitters/protobuf/reference/data-types.md index 1888cdb2e..7c7a413a0 100644 --- a/docs/emitters/protobuf/reference/data-types.md +++ b/docs/emitters/protobuf/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.Protobuf ### `Extern` {#TypeSpec.Protobuf.Extern} diff --git a/docs/emitters/protobuf/reference/decorators.md b/docs/emitters/protobuf/reference/decorators.md index 1491b78bf..551e61e91 100644 --- a/docs/emitters/protobuf/reference/decorators.md +++ b/docs/emitters/protobuf/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Protobuf ### `@field` {#@TypeSpec.Protobuf.field} diff --git a/docs/emitters/protobuf/reference/emitter.md b/docs/emitters/protobuf/reference/emitter.md index b9c8fc245..5c0ad2c42 100644 --- a/docs/emitters/protobuf/reference/emitter.md +++ b/docs/emitters/protobuf/reference/emitter.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Emitter - ## Usage 1. Via the command line diff --git a/docs/emitters/protobuf/reference/index.mdx b/docs/emitters/protobuf/reference/index.mdx index 3914200c6..5134f9379 100644 --- a/docs/emitters/protobuf/reference/index.mdx +++ b/docs/emitters/protobuf/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library and emitter for Protobuf (gRPC) ## Install diff --git a/docs/extending-typespec/basics.md b/docs/extending-typespec/basics.md index 4deefa490..c1fcc3b64 100644 --- a/docs/extending-typespec/basics.md +++ b/docs/extending-typespec/basics.md @@ -3,8 +3,6 @@ id: basics title: Creating a TypeSpec Library --- -# Creating a TypeSpec library - A TypeSpec library is a package that includes TypeSpec types, decorators, emitters or linters. These libraries are [npm packages](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) with some additional TypeSpec-specific metadata and conventions. This guide will walk you through the process of creating a new TypeSpec library, adding types to it, and distributing it on the public npm registry. Further sections will delve into the specifics of creating [decorators](create-decorators.md), [emitters](./emitters-basics.md) and [linters](./linters.md). While this guide assumes that you'll be using [TypeScript](https://typescriptlang.org) to develop your library, you can skip the TypeScript-related steps if you prefer to use plain JavaScript. diff --git a/docs/extending-typespec/create-decorators.md b/docs/extending-typespec/create-decorators.md index 3c4986ea2..a620b67fc 100644 --- a/docs/extending-typespec/create-decorators.md +++ b/docs/extending-typespec/create-decorators.md @@ -3,8 +3,6 @@ id: create-decorators title: Decorators --- -# Decorators - TypeSpec decorators are implemented as JavaScript functions. The process of creating a decorator can be divided into two parts: 1. [Declare the decorator signature in TypeSpec](#declare-the-decorator-signature) (optional but recommended) diff --git a/docs/extending-typespec/emitter-framework.md b/docs/extending-typespec/emitter-framework.md index 32f8a966b..b2490de39 100644 --- a/docs/extending-typespec/emitter-framework.md +++ b/docs/extending-typespec/emitter-framework.md @@ -3,8 +3,6 @@ id: emitter-framework title: Emitter framework --- -# Emitter framework - :::warning The emitter framework has many issues in its current form and a V2 using a completely different approach is in the works. Use with caution. ::: diff --git a/docs/extending-typespec/emitter-metadata-handling.md b/docs/extending-typespec/emitter-metadata-handling.md index 70493280e..82b068426 100644 --- a/docs/extending-typespec/emitter-metadata-handling.md +++ b/docs/extending-typespec/emitter-metadata-handling.md @@ -3,8 +3,6 @@ id: emitter-metadata-handling title: Managing metadata and visibility in REST API emitters --- -# Managing metadata and visibility in REST API emitters - Ensuring consistent handling of [automatic visibility](../libraries/http/operations.md#automatic-visibility) and [metadata](../libraries/http/operations.md#metadata) by all REST API emitters is crucial. To understand how these features work, please refer to the TypeSpec-author documentation. This guide will help you integrate these features into your own emitter correctly. The standard `/rest` library offers a JavaScript API for emitters to interpret APIs written using its decorators. We will focus on the APIs that are specifically relevant to these features. diff --git a/docs/extending-typespec/emitters-basics.md b/docs/extending-typespec/emitters-basics.md index c7ea72450..d92540d37 100644 --- a/docs/extending-typespec/emitters-basics.md +++ b/docs/extending-typespec/emitters-basics.md @@ -3,8 +3,6 @@ id: emitters title: Emitters --- -# Creating emitters - TypeSpec emitters are libraries that utilize various TypeSpec compiler APIs to reflect on the TypeSpec compilation process and generate artifacts. The TypeSpec standard library includes emitters for OpenAPI version 3.0, JSON Schema, and Protocol Buffers (Protobuf). However, you might want to emit TypeSpec to a different output format. One of the main advantages of TypeSpec is its ease of use as a single source of truth for all data shapes, and the simplicity of creating an emitter contributes significantly to this. ## Emitter design diff --git a/docs/extending-typespec/linters.md b/docs/extending-typespec/linters.md index 67ccd8ef4..3d3af314e 100644 --- a/docs/extending-typespec/linters.md +++ b/docs/extending-typespec/linters.md @@ -3,8 +3,6 @@ id: linters title: Linters --- -# Linters - ## Linter versus `onValidate` A TypeSpec library can provide an `$onValidate` hook, which can be used to validate whether the TypeSpec program is valid according to your library's rules. diff --git a/docs/extending-typespec/writing-scaffolding-template.md b/docs/extending-typespec/writing-scaffolding-template.md index 62de15cbd..8a5571e5c 100644 --- a/docs/extending-typespec/writing-scaffolding-template.md +++ b/docs/extending-typespec/writing-scaffolding-template.md @@ -2,8 +2,6 @@ title: Scaffolding templates --- -# Creating a scaffolding template - TypeSpec offers a scaffolding feature through the `tsp init` command. ```bash diff --git a/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md b/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md index e7ade3d7c..a9dfdcd2e 100644 --- a/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md +++ b/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md @@ -4,8 +4,6 @@ title: Getting Started with TypeSpec For REST APIs pagination_next: getting-started/getting-started-rest/02-operations-responses # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183 --- -# Getting Started with TypeSpec for REST APIs - ## Introduction Welcome to our tutorial on using TypeSpec to define REST APIs with HTTP. In this section, we'll introduce you to TypeSpec, help you set up your environment, and cover the basic syntax and structure of TypeSpec. By the end of this section, you'll have a solid foundation to build upon in the subsequent sections. diff --git a/docs/getting-started/getting-started-rest/02-operations-responses.md b/docs/getting-started/getting-started-rest/02-operations-responses.md index 8a840aa62..dd370f42f 100644 --- a/docs/getting-started/getting-started-rest/02-operations-responses.md +++ b/docs/getting-started/getting-started-rest/02-operations-responses.md @@ -3,8 +3,6 @@ id: 02-operations-responses title: Operations and Responses --- -# Operations and Responses - ## Introduction In this section, we'll build upon the basics we covered in the previous section. We'll define CRUD operations (Create, Read, Update, Delete) for our Pet Store API and discuss the benefits of using nested namespaces. diff --git a/docs/getting-started/getting-started-rest/03-handling-errors.md b/docs/getting-started/getting-started-rest/03-handling-errors.md index 7a0e86854..d92d05e4c 100644 --- a/docs/getting-started/getting-started-rest/03-handling-errors.md +++ b/docs/getting-started/getting-started-rest/03-handling-errors.md @@ -2,8 +2,6 @@ title: Handling Errors --- -# Handling Errors in Your REST API - ## Introduction In this section, we'll focus on handling errors in your REST API. We'll define error models and demonstrate how to add them as possible responses to your CRUD operations. diff --git a/docs/getting-started/getting-started-rest/04-common-parameters.md b/docs/getting-started/getting-started-rest/04-common-parameters.md index 066fecef7..61e7493d1 100644 --- a/docs/getting-started/getting-started-rest/04-common-parameters.md +++ b/docs/getting-started/getting-started-rest/04-common-parameters.md @@ -2,8 +2,6 @@ title: Common Parameters --- -# Reusing Common Parameters - ## Introduction In this section, we'll focus on reusing common parameters in your REST API. Common parameters are parameters that are used across multiple operations. By defining these parameters once and reusing them, we can make our API more consistent, easier to read, and easier to maintain. diff --git a/docs/getting-started/getting-started-rest/05-authentication.md b/docs/getting-started/getting-started-rest/05-authentication.md index 4365b93e7..61b1111a1 100644 --- a/docs/getting-started/getting-started-rest/05-authentication.md +++ b/docs/getting-started/getting-started-rest/05-authentication.md @@ -2,8 +2,6 @@ title: Authentication --- -# Adding Authentication to Your REST API - ## Introduction In this section, we'll focus on adding [authentication](../../libraries/http/authentication) to your REST API. We'll introduce the `@useAuth` decorator, show how to enforce authentication on specific operations, and provide an example using Bearer authentication. diff --git a/docs/getting-started/getting-started-rest/06-versioning.md b/docs/getting-started/getting-started-rest/06-versioning.md index d0fcf4873..e79f0ea3f 100644 --- a/docs/getting-started/getting-started-rest/06-versioning.md +++ b/docs/getting-started/getting-started-rest/06-versioning.md @@ -2,8 +2,6 @@ title: Versioning --- -# Versioning - ## Introduction In this section, we'll focus on implementing versioning in your REST API. Versioning allows you to manage changes to your API over time without breaking existing clients. We'll introduce the `@versioned` decorator, show how to define versions with enums, and demonstrate how to use the `@added` decorator to specify version-specific models and operations. diff --git a/docs/getting-started/getting-started-rest/07-custom-response-models.md b/docs/getting-started/getting-started-rest/07-custom-response-models.md index ecd507114..86c7245e1 100644 --- a/docs/getting-started/getting-started-rest/07-custom-response-models.md +++ b/docs/getting-started/getting-started-rest/07-custom-response-models.md @@ -2,8 +2,6 @@ title: Custom Response Models --- -# Custom Response Models - ## Introduction In this section, we'll focus on creating custom response models and demonstrate how to use them in your API operations. We'll also incorporate predefined response models from the TypeSpec HTTP library. diff --git a/docs/getting-started/getting-started-rest/08-conclusion.md b/docs/getting-started/getting-started-rest/08-conclusion.md index 4d0071cd4..5a9fcb875 100644 --- a/docs/getting-started/getting-started-rest/08-conclusion.md +++ b/docs/getting-started/getting-started-rest/08-conclusion.md @@ -2,8 +2,6 @@ title: Conclusion --- -# Conclusion - ## Recap of Key Concepts Throughout this tutorial, we've covered a wide range of topics to help you build a comprehensive REST API using TypeSpec. Here's a brief recap of the main concepts we explored: diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md index 46f112b1e..2a57a3236 100644 --- a/docs/getting-started/getting-started.md +++ b/docs/getting-started/getting-started.md @@ -3,6 +3,4 @@ id: getting-started title: Getting Started --- -# Getting started with TypeSpec - - [Get started with TypeSpec for REST](./getting-started-rest/01-setup-basic-syntax.md) diff --git a/docs/getting-started/typespec-for-openapi-dev.md b/docs/getting-started/typespec-for-openapi-dev.md index a7c5b42d0..949bff878 100644 --- a/docs/getting-started/typespec-for-openapi-dev.md +++ b/docs/getting-started/typespec-for-openapi-dev.md @@ -2,8 +2,6 @@ title: TypeSpec For OpenAPI Developer --- -# TypeSpec for the OpenAPI developer - This guide is an introduction to TypeSpec using concepts that will be familiar to developers that either build or use API definitions in OpenAPI v2 or v3. diff --git a/docs/handbook/cli.md b/docs/handbook/cli.md index 094437a69..9e49446a7 100644 --- a/docs/handbook/cli.md +++ b/docs/handbook/cli.md @@ -3,8 +3,6 @@ id: cli title: Cli usage --- -# Usage - See full usage documentation by typing `tsp --help`: ```bash diff --git a/docs/handbook/configuration/configuration.md b/docs/handbook/configuration/configuration.md index d44845263..367f502be 100644 --- a/docs/handbook/configuration/configuration.md +++ b/docs/handbook/configuration/configuration.md @@ -2,8 +2,6 @@ title: Configuration --- -# Compiler and library configurations - The TypeSpec compiler and libraries can be configured either via a [configuration file](#configuration-file) or command line flags. ## Configuration file diff --git a/docs/handbook/configuration/tracing.md b/docs/handbook/configuration/tracing.md index 89eaaa8da..9416d4944 100644 --- a/docs/handbook/configuration/tracing.md +++ b/docs/handbook/configuration/tracing.md @@ -2,8 +2,6 @@ title: Tracing --- -# Tracing - The TypeSpec Compiler, by default, builds without any debug information. The standard output is minimal, only including any `warning` or `error` diagnostics that occur during the compilation process. However, the compiler does collect additional information that can be accessed using the `--trace` command-line interface (CLI) flag. diff --git a/docs/handbook/faq.md b/docs/handbook/faq.md index 196f25cc0..f186c8106 100644 --- a/docs/handbook/faq.md +++ b/docs/handbook/faq.md @@ -3,8 +3,6 @@ id: faq title: FAQ --- -# Frequently Asked Questions (FAQ) - ## I'm getting the error `Cannot find package 'x' imported from 'y'`, but I'm not using this package. Why? This issue typically arises when package 'y' has a `peerDependency` on package 'x', and package 'x' hasn't been installed. This can occur if you're using a version of npm that's older than version 7, as these older versions don't automatically install peerDependencies. You would need to install them manually. diff --git a/docs/handbook/formatter.md b/docs/handbook/formatter.md index a4363449a..2a86352d8 100644 --- a/docs/handbook/formatter.md +++ b/docs/handbook/formatter.md @@ -3,8 +3,6 @@ id: formatter title: Formatter --- -# Formatter - TypeSpec comes with a built-in formatter. The formatter can be used in different ways: - [Via the cli](#via-the-cli) diff --git a/docs/handbook/releases.md b/docs/handbook/releases.md index 69b00547f..04906a2f0 100644 --- a/docs/handbook/releases.md +++ b/docs/handbook/releases.md @@ -3,8 +3,6 @@ id: releases title: Releases --- -# Releases - ## Versioning strategy for packages TypeSpec is currently in its development phase, and all packages are released with a `0.` major version. Each minor version may introduce some breaking changes to the TypeSpec language, library API, or both. These changes are documented [here](../release-notes). diff --git a/docs/handbook/style-guide.md b/docs/handbook/style-guide.md index 9c7d0e66c..b009ccdf9 100644 --- a/docs/handbook/style-guide.md +++ b/docs/handbook/style-guide.md @@ -2,8 +2,6 @@ title: Style guide --- -# TypeSpec language style guide - This guide offers a recommended set of naming conventions to follow when drafting a TypeSpec specification. :::info diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md index 969f8ef6d..07f197c12 100644 --- a/docs/introduction/installation.md +++ b/docs/introduction/installation.md @@ -4,8 +4,6 @@ title: Installation slug: / --- -# Installation - ## Requirements Install [Node.js 20 LTS](https://nodejs.org/en/download/) and ensure you can run the `npm` command in a command prompt: diff --git a/docs/language-basics/alias.md b/docs/language-basics/alias.md index d01011261..ed29ec9ee 100644 --- a/docs/language-basics/alias.md +++ b/docs/language-basics/alias.md @@ -3,8 +3,6 @@ id: aliases title: Aliases --- -# Aliases - Aliases are a convenient way to define shorthand for types, especially when dealing with complex expressions. They simplify the syntax but don't have a representation in the type graph. As a result, you can't decorate aliases. If you need to give an alternate name to a model, use [`model is`](./models.md). You can define an alias using the `alias` keyword. diff --git a/docs/language-basics/built-in-types.md b/docs/language-basics/built-in-types.md index d70a40cf2..380c4071f 100644 --- a/docs/language-basics/built-in-types.md +++ b/docs/language-basics/built-in-types.md @@ -3,8 +3,6 @@ id: built-in-types title: Built-in types --- -# Built-in types - TypeSpec Standard Library provide some built-in types that can be used to build more complex types. Built in types are related to each other according to the rules described in [type relations](../language-basics/type-relations.md). diff --git a/docs/language-basics/decorators.md b/docs/language-basics/decorators.md index aa57714ad..2cdeb3c05 100644 --- a/docs/language-basics/decorators.md +++ b/docs/language-basics/decorators.md @@ -3,8 +3,6 @@ id: decorators title: Decorators --- -# Decorators - Decorators in TypeSpec allow developers to attach metadata to types within a TypeSpec program. They can also be used to compute types based on their inputs. Decorators form the core of TypeSpec's extensibility, providing the flexibility to describe a wide variety of APIs and associated metadata such as documentation, constraints, samples, and more. A range of TypeSpec constructs can be decorated, including [namespaces](./namespaces.md), [operations](./operations.md) and their parameters, and [models](./models.md) and their members. diff --git a/docs/language-basics/documentation.md b/docs/language-basics/documentation.md index 52e5149dd..6f6f24656 100644 --- a/docs/language-basics/documentation.md +++ b/docs/language-basics/documentation.md @@ -3,11 +3,9 @@ id: documentation title: Documentation --- -# Documentation - Documentation is a vital aspect of any API. TypeSpec offers several ways to document your API, including doc comments and decorators. -# Approaches to documenting APIs +## Approaches to documenting APIs TypeSpec provides two primary methods for documenting your API: @@ -77,7 +75,7 @@ As shown in the previous example, doc comments can use certain tags to document | `@template` | Document a template parameter | `@template T the resource type` | | `@example` (unofficial) | Show examples | `@example \`model Foo {}\` ` | -# Comments +## Comments TypeSpec supports both single-line and multi-line comments. Single-line comments start with `//` and continue until the end of the line. Multi-line comments start with `/*` and continue until the closing `*/` is encountered. diff --git a/docs/language-basics/enums.md b/docs/language-basics/enums.md index 7abb25dfd..829b5262f 100644 --- a/docs/language-basics/enums.md +++ b/docs/language-basics/enums.md @@ -3,8 +3,6 @@ id: enums title: Enums --- -# Enums - Enums, short for enumerations, provide a way for developers to define a collection of named constants. They are useful for documenting the purpose of the code or for establishing a set of distinct scenarios. Enums can be either numeric or string-based. For other data types, consider using [unions](./unions.md). ## The basics diff --git a/docs/language-basics/identifiers.md b/docs/language-basics/identifiers.md index 2f4d0e95c..5de21c940 100644 --- a/docs/language-basics/identifiers.md +++ b/docs/language-basics/identifiers.md @@ -2,8 +2,6 @@ title: Identifiers --- -# Identifiers - Identifiers are used to name models, enums, properties, and other entities in TypeSpec. An identifier is a sequence of one or more characters that must start with a letter, emoji, underscore, or dollar sign, and be followed by letters, numbers, emoji, underscores, or dollar signs. TypeSpec implements [UAX31-R1b stable identifiers](http://www.unicode.org/reports/tr31/#R1b) with the [emoji profile](http://www.unicode.org/reports/tr31/#Emoji_Profile). Examples: diff --git a/docs/language-basics/imports.md b/docs/language-basics/imports.md index 7ec9267e1..de6ff9462 100644 --- a/docs/language-basics/imports.md +++ b/docs/language-basics/imports.md @@ -3,8 +3,6 @@ id: imports title: Imports --- -# Importing files and libraries in TypeSpec - Imports are used to include files or libraries into your TypeSpec program. When compiling a TypeSpec file, you specify the path to your root TypeSpec file, typically named "main.tsp". From this root file, any imported files are added to your program. If a directory is imported, TypeSpec will search for a `main.tsp` file within that directory. The path specified in the import must either start with `"./"` or `"../"`, or be an absolute path. The path should either point to a directory, or have an extension of either ".tsp" or ".js". The examples below illustrate how to use imports to assemble a TypeSpec program from multiple files: diff --git a/docs/language-basics/interfaces.md b/docs/language-basics/interfaces.md index 01452f2c9..28df25ffd 100644 --- a/docs/language-basics/interfaces.md +++ b/docs/language-basics/interfaces.md @@ -3,8 +3,6 @@ id: interfaces title: Interfaces --- -# Interfaces - Interfaces are useful for grouping and reusing [operations](./operations.md). You can declare interfaces using the `interface` keyword. Its name must be an [`identifier`](./identifiers.md). diff --git a/docs/language-basics/intersections.md b/docs/language-basics/intersections.md index 89e6c36f9..6023eaf45 100644 --- a/docs/language-basics/intersections.md +++ b/docs/language-basics/intersections.md @@ -3,8 +3,6 @@ id: intersections title: Intersections --- -# Intersections - Intersections in programming define a type that must encompass all the constituents of the intersection. You can declare an intersection using the `&` operator. ```typespec diff --git a/docs/language-basics/models.md b/docs/language-basics/models.md index d59170942..c3ad0749d 100644 --- a/docs/language-basics/models.md +++ b/docs/language-basics/models.md @@ -3,8 +3,6 @@ id: models title: Models --- -# Models - Models in TypeSpec are utilized to define the structure or schema of data. ## Types of models diff --git a/docs/language-basics/namespaces.md b/docs/language-basics/namespaces.md index 5ac0a7102..6f4d6baa1 100644 --- a/docs/language-basics/namespaces.md +++ b/docs/language-basics/namespaces.md @@ -3,8 +3,6 @@ id: namespaces title: Namespaces --- -# Namespaces - Namespaces in TypeSpec allow you to group related types together. This organization makes your types easier to locate and helps avoid naming conflicts. Namespaces are merged across files, enabling you to reference any type from anywhere in your TypeSpec program using its namespace. ## Basics diff --git a/docs/language-basics/operations.md b/docs/language-basics/operations.md index 4f774eeaf..c503e6d83 100644 --- a/docs/language-basics/operations.md +++ b/docs/language-basics/operations.md @@ -3,8 +3,6 @@ id: operations title: Operations --- -# Operations - Operations are essentially service endpoints, characterized by an operation name, parameters, and a return type. You can declare operations using the `op` keyword. Its name must be an [`identifier`](./identifiers.md). diff --git a/docs/language-basics/overview.md b/docs/language-basics/overview.md index bf4a611ad..0ab9329cb 100644 --- a/docs/language-basics/overview.md +++ b/docs/language-basics/overview.md @@ -3,8 +3,6 @@ id: overview title: Overview --- -# Language Overview - This document provides a concise overview of the language concepts in TypeSpec. It serves as a quick reference guide rather than an in-depth tutorial. ## Declarations diff --git a/docs/language-basics/scalars.md b/docs/language-basics/scalars.md index 93a97f2f5..fbb30c6ed 100644 --- a/docs/language-basics/scalars.md +++ b/docs/language-basics/scalars.md @@ -2,8 +2,6 @@ title: Scalars --- -# Scalars - Scalars are simple types that don't have any fields. Examples of these include `string`, `int32`, `boolean`, and so on. You can declare a scalar by using the `scalar` keyword. Its name must be an [`identifier`](./identifiers.md). diff --git a/docs/language-basics/templates.md b/docs/language-basics/templates.md index 857b93de8..65c087bc3 100644 --- a/docs/language-basics/templates.md +++ b/docs/language-basics/templates.md @@ -3,8 +3,6 @@ id: templates title: Templates --- -# Templates - Templates are a powerful tool that allow users to customize certain aspects of a type. Similar to generics in other programming languages, templates define template parameters that users can specify when referencing the type. Templates can be applied to: diff --git a/docs/language-basics/type-literals.md b/docs/language-basics/type-literals.md index 2de0abad5..7873ecb5f 100644 --- a/docs/language-basics/type-literals.md +++ b/docs/language-basics/type-literals.md @@ -3,8 +3,6 @@ id: type-literals title: Type Literals --- -# Type literals - When designing APIs, it's common to define the structure of the API in terms of specific literal values. For instance, an operation might return a specific integer status code, or a model member might be one of a few specific string values. It's also useful to pass specific literal values to decorators. TypeSpec supports string, number, and boolean literal values to cater to these needs. ## String literals diff --git a/docs/language-basics/type-relations.md b/docs/language-basics/type-relations.md index aa1ef1e8e..217b66b99 100644 --- a/docs/language-basics/type-relations.md +++ b/docs/language-basics/type-relations.md @@ -3,8 +3,6 @@ id: type-relations title: Type Relations --- -# Type relations - ## Type hierarchy ```mermaid diff --git a/docs/language-basics/unions.md b/docs/language-basics/unions.md index 9c1014c0f..905091889 100644 --- a/docs/language-basics/unions.md +++ b/docs/language-basics/unions.md @@ -3,8 +3,6 @@ id: unions title: Unions --- -# Unions - Unions define a type that must be exactly one of several possible variants. There are two types of unions: - Union expressions diff --git a/docs/language-basics/values.md b/docs/language-basics/values.md index 4bed4774f..8b3109d2c 100644 --- a/docs/language-basics/values.md +++ b/docs/language-basics/values.md @@ -3,8 +3,6 @@ id: values title: Values --- -# Values - TypeSpec can define values in addition to types. Values are useful in an API description to define default values for types or provide example values. They are also useful when passing data to decorators, and for template parameters that are ultimately passed to decorators or used as default values. Values cannot be used as types, and types cannot be used as values, they are completely separate. However, string, number, boolean, and null literals can be either a type or a value depending on context (see also [scalar literals](#scalar-literals)). Additionally, union and enum member references may produce a type or a value depending on context (see also [enum member & union variant references](#enum-member--union-variant-references)). diff --git a/docs/libraries/events/reference/decorators.md b/docs/libraries/events/reference/decorators.md index 69772a8bb..302ea7e5a 100644 --- a/docs/libraries/events/reference/decorators.md +++ b/docs/libraries/events/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Events ### `@contentType` {#@TypeSpec.Events.contentType} diff --git a/docs/libraries/events/reference/index.mdx b/docs/libraries/events/reference/index.mdx index 514d08760..5ca619d1c 100644 --- a/docs/libraries/events/reference/index.mdx +++ b/docs/libraries/events/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library providing events bindings ## Install diff --git a/docs/libraries/http-server-javascript/reference/emitter.md b/docs/libraries/http-server-javascript/reference/emitter.md index 48a590d5e..a1299e9cd 100644 --- a/docs/libraries/http-server-javascript/reference/emitter.md +++ b/docs/libraries/http-server-javascript/reference/emitter.md @@ -4,7 +4,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Emitter + ## Usage diff --git a/docs/libraries/http-server-javascript/reference/index.mdx b/docs/libraries/http-server-javascript/reference/index.mdx index f49d39fb1..51d1c36d5 100644 --- a/docs/libraries/http-server-javascript/reference/index.mdx +++ b/docs/libraries/http-server-javascript/reference/index.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview + TypeSpec HTTP server code generator for JavaScript diff --git a/docs/libraries/http/authentication.md b/docs/libraries/http/authentication.md index 04a7a9fa0..4a1779f40 100644 --- a/docs/libraries/http/authentication.md +++ b/docs/libraries/http/authentication.md @@ -2,8 +2,6 @@ title: Authentication --- -# Configure Http Authentication - ## Configure Authentication can be configured using the `@useAuth` decorator on a service namespace, sub-namespace, interface or operation. diff --git a/docs/libraries/http/examples.md b/docs/libraries/http/examples.md index f6b0700c9..9c4cd7e5f 100644 --- a/docs/libraries/http/examples.md +++ b/docs/libraries/http/examples.md @@ -2,8 +2,6 @@ title: Examples --- -# Http Examples - See [examples docs](../../standard-library/examples.md) for general information about examples. ## Multiple responses diff --git a/docs/libraries/http/operations.md b/docs/libraries/http/operations.md index 9071328c5..dcc4d085f 100644 --- a/docs/libraries/http/operations.md +++ b/docs/libraries/http/operations.md @@ -2,8 +2,6 @@ title: Operations --- -# Http Operations - ## Operation verb **Default behavior:** diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index 549e8fc88..e36be1cd4 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.Http ### `AcceptedResponse` {#TypeSpec.Http.AcceptedResponse} diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index a55f42907..d4f2a49f0 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Http ### `@body` {#@TypeSpec.Http.body} diff --git a/docs/libraries/http/reference/index.mdx b/docs/libraries/http/reference/index.mdx index 352ea8d95..865df0b23 100644 --- a/docs/libraries/http/reference/index.mdx +++ b/docs/libraries/http/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec HTTP protocol binding ## Install diff --git a/docs/libraries/http/reference/linter.md b/docs/libraries/http/reference/linter.md index e36573415..5440e045d 100644 --- a/docs/libraries/http/reference/linter.md +++ b/docs/libraries/http/reference/linter.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Linter - ## Usage Add the following in `tspconfig.yaml`: diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 04831f5d8..043a4ec50 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.OpenAPI ### `AdditionalInfo` {#TypeSpec.OpenAPI.AdditionalInfo} diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 90b23016b..be7cf1831 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.OpenAPI ### `@defaultResponse` {#@TypeSpec.OpenAPI.defaultResponse} diff --git a/docs/libraries/openapi/reference/index.mdx b/docs/libraries/openapi/reference/index.mdx index 7626cf0bd..6510dee91 100644 --- a/docs/libraries/openapi/reference/index.mdx +++ b/docs/libraries/openapi/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library providing OpenAPI concepts ## Install diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index 6b1dcd5d1..519042ec0 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.Rest ### `ResourceLocation` {#TypeSpec.Rest.ResourceLocation} diff --git a/docs/libraries/rest/reference/decorators.md b/docs/libraries/rest/reference/decorators.md index 39ec842b5..c9862cab6 100644 --- a/docs/libraries/rest/reference/decorators.md +++ b/docs/libraries/rest/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Rest ### `@action` {#@TypeSpec.Rest.action} diff --git a/docs/libraries/rest/reference/index.mdx b/docs/libraries/rest/reference/index.mdx index 158097c6d..a30a6786c 100644 --- a/docs/libraries/rest/reference/index.mdx +++ b/docs/libraries/rest/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec REST protocol binding ## Install diff --git a/docs/libraries/rest/reference/interfaces.md b/docs/libraries/rest/reference/interfaces.md index 14876462b..c08054e13 100644 --- a/docs/libraries/rest/reference/interfaces.md +++ b/docs/libraries/rest/reference/interfaces.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Interfaces and Operations - ## TypeSpec.Rest.Resource ### `ExtensionResourceCollectionOperations` {#TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations} diff --git a/docs/libraries/rest/resource-routing.md b/docs/libraries/rest/resource-routing.md index a76d4b607..69be7e07f 100644 --- a/docs/libraries/rest/resource-routing.md +++ b/docs/libraries/rest/resource-routing.md @@ -2,8 +2,6 @@ title: Resource and routes --- -# Resources & routes - Resources are operations that are grouped in a namespace. You declare such a namespace by adding the `@route` decorator to provide the path to that resource: ```typespec diff --git a/docs/libraries/sse/reference/data-types.md b/docs/libraries/sse/reference/data-types.md index d32287739..69f4dbb19 100644 --- a/docs/libraries/sse/reference/data-types.md +++ b/docs/libraries/sse/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.SSE ### `SSEStream` {#TypeSpec.SSE.SSEStream} diff --git a/docs/libraries/sse/reference/decorators.md b/docs/libraries/sse/reference/decorators.md index a92b00db9..072c6d53b 100644 --- a/docs/libraries/sse/reference/decorators.md +++ b/docs/libraries/sse/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.SSE ### `@terminalEvent` {#@TypeSpec.SSE.terminalEvent} diff --git a/docs/libraries/sse/reference/index.mdx b/docs/libraries/sse/reference/index.mdx index fd60078eb..298547e88 100644 --- a/docs/libraries/sse/reference/index.mdx +++ b/docs/libraries/sse/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library providing server sent events bindings ## Install diff --git a/docs/libraries/stream/reference/data-types.md b/docs/libraries/stream/reference/data-types.md index 6b52f0434..45b143c39 100644 --- a/docs/libraries/stream/reference/data-types.md +++ b/docs/libraries/stream/reference/data-types.md @@ -4,7 +4,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types + ## TypeSpec.Streams diff --git a/docs/libraries/stream/reference/decorators.md b/docs/libraries/stream/reference/decorators.md index 7baec7a7b..13043a848 100644 --- a/docs/libraries/stream/reference/decorators.md +++ b/docs/libraries/stream/reference/decorators.md @@ -4,7 +4,7 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators + ## TypeSpec.Streams diff --git a/docs/libraries/stream/reference/index.mdx b/docs/libraries/stream/reference/index.mdx index 854a1d24a..a022277a6 100644 --- a/docs/libraries/stream/reference/index.mdx +++ b/docs/libraries/stream/reference/index.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview + TypeSpec library providing stream bindings diff --git a/docs/libraries/streams/reference/data-types.md b/docs/libraries/streams/reference/data-types.md index 6b52f0434..646175c4e 100644 --- a/docs/libraries/streams/reference/data-types.md +++ b/docs/libraries/streams/reference/data-types.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types - ## TypeSpec.Streams ### `Stream` {#TypeSpec.Streams.Stream} diff --git a/docs/libraries/streams/reference/decorators.md b/docs/libraries/streams/reference/decorators.md index 7baec7a7b..ebca14470 100644 --- a/docs/libraries/streams/reference/decorators.md +++ b/docs/libraries/streams/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Streams ### `@streamOf` {#@TypeSpec.Streams.streamOf} diff --git a/docs/libraries/streams/reference/index.mdx b/docs/libraries/streams/reference/index.mdx index 854a1d24a..840377595 100644 --- a/docs/libraries/streams/reference/index.mdx +++ b/docs/libraries/streams/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library providing stream bindings ## Install diff --git a/docs/libraries/versioning/reference/decorators.md b/docs/libraries/versioning/reference/decorators.md index 536aace65..7630dff3d 100644 --- a/docs/libraries/versioning/reference/decorators.md +++ b/docs/libraries/versioning/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Versioning ### `@added` {#@TypeSpec.Versioning.added} diff --git a/docs/libraries/versioning/reference/index.mdx b/docs/libraries/versioning/reference/index.mdx index 1a9826b03..ca9ce02cb 100644 --- a/docs/libraries/versioning/reference/index.mdx +++ b/docs/libraries/versioning/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library for declaring and emitting versioned APIs ## Install diff --git a/docs/libraries/xml/guide.md b/docs/libraries/xml/guide.md index f7860abe9..a13d302aa 100644 --- a/docs/libraries/xml/guide.md +++ b/docs/libraries/xml/guide.md @@ -2,8 +2,6 @@ title: Guide --- -# Xml Library - ## Default encoding of scalars As in Json we have some [default handling](https://typespec.io/docs/libraries/http/encoding#bytes) of the common scalars like `utcDateTime` diff --git a/docs/libraries/xml/reference/decorators.md b/docs/libraries/xml/reference/decorators.md index d1917fce4..c13536f91 100644 --- a/docs/libraries/xml/reference/decorators.md +++ b/docs/libraries/xml/reference/decorators.md @@ -4,8 +4,6 @@ toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Decorators - ## TypeSpec.Xml ### `@attribute` {#@TypeSpec.Xml.attribute} diff --git a/docs/libraries/xml/reference/index.mdx b/docs/libraries/xml/reference/index.mdx index 6b1f7600a..898bc8894 100644 --- a/docs/libraries/xml/reference/index.mdx +++ b/docs/libraries/xml/reference/index.mdx @@ -8,8 +8,6 @@ toc_max_heading_level: 3 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Overview - TypeSpec library providing xml bindings ## Install diff --git a/docs/release-notes/release-2022-07-08.md b/docs/release-notes/release-2022-07-08.md index 84142599b..62ec45313 100644 --- a/docs/release-notes/release-2022-07-08.md +++ b/docs/release-notes/release-2022-07-08.md @@ -2,8 +2,6 @@ title: July 2022 --- -# Release Notes July 2022 (2022-07-08) - This release contains **breaking changes** - Emitter options normalized to use kebab-case instead of camelCase. diff --git a/docs/release-notes/release-2022-08-10.md b/docs/release-notes/release-2022-08-10.md index 8e58c4062..add8efbe0 100644 --- a/docs/release-notes/release-2022-08-10.md +++ b/docs/release-notes/release-2022-08-10.md @@ -2,8 +2,6 @@ title: August 2022 --- -# Release Notes August 2022 (2022-08-10) - This release contains **breaking changes** - Operation parameters without decorators diff --git a/docs/release-notes/release-2022-09-07.md b/docs/release-notes/release-2022-09-07.md index 2d65e49e4..08eb6745b 100644 --- a/docs/release-notes/release-2022-09-07.md +++ b/docs/release-notes/release-2022-09-07.md @@ -2,8 +2,6 @@ title: September 2022 --- -# Release Notes September 2022 (2022-09-07) - This release contains **breaking changes**: - **`Api`**: Remove `Type` suffix diff --git a/docs/release-notes/release-2022-10-12.md b/docs/release-notes/release-2022-10-12.md index 113c12075..5af411ad4 100644 --- a/docs/release-notes/release-2022-10-12.md +++ b/docs/release-notes/release-2022-10-12.md @@ -2,8 +2,6 @@ title: October 2022 --- -# Release Notes October 2022 (2022-10-12) - This release contains **breaking changes**: - **`TypeSpec`**: Cannot `extends` or `is` a model expression via alias diff --git a/docs/release-notes/release-2022-12-07.md b/docs/release-notes/release-2022-12-07.md index de2cf660e..cb2c28b34 100644 --- a/docs/release-notes/release-2022-12-07.md +++ b/docs/release-notes/release-2022-12-07.md @@ -2,8 +2,6 @@ title: December 2022 --- -# Release Notes December 2022 (2022-12-07) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-01-12.md b/docs/release-notes/release-2023-01-12.md index 534e6c1c7..fd9989e5e 100644 --- a/docs/release-notes/release-2023-01-12.md +++ b/docs/release-notes/release-2023-01-12.md @@ -2,8 +2,6 @@ title: January 2023 --- -# Release Notes January 2023 (2023-01-12) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-02-07.md b/docs/release-notes/release-2023-02-07.md index b093ca047..9999ad5ca 100644 --- a/docs/release-notes/release-2023-02-07.md +++ b/docs/release-notes/release-2023-02-07.md @@ -2,8 +2,6 @@ title: February 2023 --- -# Release Notes February 2023 (2023-02-07) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-03-13.md b/docs/release-notes/release-2023-03-13.md index 843e0c58f..2a0f6c353 100644 --- a/docs/release-notes/release-2023-03-13.md +++ b/docs/release-notes/release-2023-03-13.md @@ -2,8 +2,6 @@ title: March 2023 --- -# Release Notes March 2023 (2023-03-13) - :::danger This release contains **breaking changes** diff --git a/docs/release-notes/release-2023-04-11.md b/docs/release-notes/release-2023-04-11.md index 6f0fa5377..289bd7366 100644 --- a/docs/release-notes/release-2023-04-11.md +++ b/docs/release-notes/release-2023-04-11.md @@ -2,8 +2,6 @@ title: April 2023 --- -# Release Notes April 2023 (2023-04-11) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-05-10.md b/docs/release-notes/release-2023-05-10.md index 249a9b077..3d85e38e4 100644 --- a/docs/release-notes/release-2023-05-10.md +++ b/docs/release-notes/release-2023-05-10.md @@ -2,8 +2,6 @@ title: May 2023 --- -# Release Notes May 2023 (2023-05-10) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-06-06.md b/docs/release-notes/release-2023-06-06.md index d8df3c951..5e297fd89 100644 --- a/docs/release-notes/release-2023-06-06.md +++ b/docs/release-notes/release-2023-06-06.md @@ -2,8 +2,6 @@ title: June 2023 --- -# Release Notes June 2023 (2023-06-06) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-07-11.md b/docs/release-notes/release-2023-07-11.md index b03fbd7e9..e90e1096e 100644 --- a/docs/release-notes/release-2023-07-11.md +++ b/docs/release-notes/release-2023-07-11.md @@ -2,8 +2,6 @@ title: July 2023 --- -# Release Notes July 2023 (2023-07-11) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-08-08.md b/docs/release-notes/release-2023-08-08.md index 2258de93d..3402ffee5 100644 --- a/docs/release-notes/release-2023-08-08.md +++ b/docs/release-notes/release-2023-08-08.md @@ -2,8 +2,6 @@ title: August 2023 --- -# Release Notes August 2023 (2023-08-08) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-09-12.md b/docs/release-notes/release-2023-09-12.md index ba0bf6674..7e8e1cad8 100644 --- a/docs/release-notes/release-2023-09-12.md +++ b/docs/release-notes/release-2023-09-12.md @@ -2,8 +2,6 @@ title: September 2023 --- -# Release Notes September 2023 (2023-09-12) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-10-11.md b/docs/release-notes/release-2023-10-11.md index 8bde62a9b..f61e02b86 100644 --- a/docs/release-notes/release-2023-10-11.md +++ b/docs/release-notes/release-2023-10-11.md @@ -2,8 +2,6 @@ title: October 2023 --- -# Release Notes October 2023 (2023-10-11) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-11-07.md b/docs/release-notes/release-2023-11-07.md index 7f4de3662..242a848cb 100644 --- a/docs/release-notes/release-2023-11-07.md +++ b/docs/release-notes/release-2023-11-07.md @@ -2,8 +2,6 @@ title: November 2023 --- -# Release Notes November 2023 (2023-11-07) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2023-12-06.md b/docs/release-notes/release-2023-12-06.md index b68f00beb..b578f787d 100644 --- a/docs/release-notes/release-2023-12-06.md +++ b/docs/release-notes/release-2023-12-06.md @@ -2,8 +2,6 @@ title: December 2023 --- -# Release Notes December 2023 (2023-12-06) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2024-01-23.md b/docs/release-notes/release-2024-01-23.md index 1c2105495..1011836dc 100644 --- a/docs/release-notes/release-2024-01-23.md +++ b/docs/release-notes/release-2024-01-23.md @@ -2,8 +2,6 @@ title: January 2024 --- -# Release Notes January 2024 (2024-01-23) - :::danger This release contains **breaking changes** ::: diff --git a/docs/release-notes/release-2024-02-06.md b/docs/release-notes/release-2024-02-06.md index 0ff2d1861..701e96b09 100644 --- a/docs/release-notes/release-2024-02-06.md +++ b/docs/release-notes/release-2024-02-06.md @@ -2,8 +2,6 @@ title: February 2024 --- -# Release Notes February 2024 (2024-02-06) - ## Release of VSCode and Visual Studio extensions - [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=typespec.typespec-vscode) diff --git a/docs/release-notes/release-2024-03-05.md b/docs/release-notes/release-2024-03-05.md index c6ce8723e..7e9a7ae73 100644 --- a/docs/release-notes/release-2024-03-05.md +++ b/docs/release-notes/release-2024-03-05.md @@ -2,8 +2,6 @@ title: March 2024 --- -# Release Notes March 2024 (2024-03-05) - :::warning This release contains breaking changes and deprecations ::: diff --git a/docs/release-notes/release-2024-04-02.md b/docs/release-notes/release-2024-04-02.md index 590557a3f..b1149f7ed 100644 --- a/docs/release-notes/release-2024-04-02.md +++ b/docs/release-notes/release-2024-04-02.md @@ -2,8 +2,6 @@ title: 0.55 - April 2024 --- -# Release Notes Version 0.55 - April 2024 - :::warning This release contains deprecations ::: diff --git a/docs/release-notes/release-2024-05-07.md b/docs/release-notes/release-2024-05-07.md index 0fcec11b0..65f9bfa59 100644 --- a/docs/release-notes/release-2024-05-07.md +++ b/docs/release-notes/release-2024-05-07.md @@ -2,8 +2,6 @@ title: 0.56 - May 2024 --- -# Release Notes Version 0.56 - May 2024 - :::warning This release contains breaking changes ::: diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index ae1639782..dfa258387 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -3,7 +3,6 @@ title: "Built-in Data types" toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Data types ## TypeSpec ### `Array` {#Array} diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index d30994aa5..6ea1cc138 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -3,7 +3,6 @@ title: "Built-in Decorators" toc_min_heading_level: 2 toc_max_heading_level: 3 --- -# Built-in Decorators ## TypeSpec ### `@deprecated` {#@deprecated} :::warning diff --git a/docs/standard-library/examples.md b/docs/standard-library/examples.md index 7ee382b62..fe8522056 100644 --- a/docs/standard-library/examples.md +++ b/docs/standard-library/examples.md @@ -2,8 +2,6 @@ title: Examples --- -# Examples - TypeSpec provide 2 decorators `@example` and `@opExample` to provide some examples for the types and operations. With those decorators the examples must be provided as TypeSpec values that should be assignable to the type or operation parameter/return types. diff --git a/packages/eslint-plugin-typespec/docs/rules/call-decorator.md b/packages/eslint-plugin-typespec/docs/rules/call-decorator.md index 4be26e7ba..b4d98d505 100644 --- a/packages/eslint-plugin-typespec/docs/rules/call-decorator.md +++ b/packages/eslint-plugin-typespec/docs/rules/call-decorator.md @@ -1,5 +1,3 @@ -# `call-decorator` - Enforces calling other TypeSpec decorator using `context.call` instead of calling the decorator function directly. Calling the decorator function directly can result in diagnostics with incorrect location. diff --git a/packages/http-client-csharp/generator/docs/cadl-ranch.md b/packages/http-client-csharp/generator/docs/cadl-ranch.md index 142f47a1e..bf088c247 100644 --- a/packages/http-client-csharp/generator/docs/cadl-ranch.md +++ b/packages/http-client-csharp/generator/docs/cadl-ranch.md @@ -1,7 +1,5 @@ -# CadlRanch Testing - By default all tests under the [http folder](https://github.com/Azure/cadl-ranch/tree/main/packages/cadl-ranch-specs/http) and excluding the [azure folder](https://github.com/Azure/cadl-ranch/tree/main/packages/cadl-ranch-specs/http/azure) will be generated. In order to get coverage for a test within one of the specs you must write a test case that executes the operation. ## Generating CadlRanchTests diff --git a/packages/http-client-csharp/generator/docs/generate/options.md b/packages/http-client-csharp/generator/docs/generate/options.md index a54a95794..58a1f4c30 100644 --- a/packages/http-client-csharp/generator/docs/generate/options.md +++ b/packages/http-client-csharp/generator/docs/generate/options.md @@ -1,5 +1,3 @@ -# Microsoft Generator CSharp Usage & Options - The command line usage of the generator is comprised of the following: > `mgc.exe [DIRECTORY] [additional options]` diff --git a/packages/http/README.md b/packages/http/README.md index 837b28a6e..f96ba37e1 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -8,9 +8,7 @@ TypeSpec HTTP protocol binding npm install @typespec/http ``` -## Linter - -### Usage +## Usage Add the following in `tspconfig.yaml`: @@ -20,13 +18,13 @@ linter: - "@typespec/http/all" ``` -### RuleSets +## RuleSets Available ruleSets: - `@typespec/http/all` -### Rules +## Rules | Name | Description | | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index ccc84c542..592b9c673 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -26,9 +26,7 @@ model Car { } ``` -## Emitter - -### Usage +## Usage 1. Via the command line @@ -53,15 +51,15 @@ options: option: value ``` -### Emitter options +## Emitter options -#### `file-type` +### `file-type` **Type:** `"yaml" | "json"` Serialize the schema as either yaml or json. -#### `int64-strategy` +### `int64-strategy` **Type:** `"string" | "number"` @@ -70,19 +68,19 @@ How to handle 64 bit integers on the wire. Options are: - string: serialize as a string (widely interoperable) - number: serialize as a number (not widely interoperable) -#### `bundleId` +### `bundleId` **Type:** `string` When provided, bundle all the schemas into a single json schema document with schemas under $defs. The provided id is the id of the root document and is also used for the file name. -#### `emitAllModels` +### `emitAllModels` **Type:** `boolean` When true, emit all model declarations to JSON Schema without requiring the @jsonSchema decorator. -#### `emitAllRefs` +### `emitAllRefs` **Type:** `boolean` diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md index 6427230ab..cd139f049 100644 --- a/packages/openapi3/README.md +++ b/packages/openapi3/README.md @@ -8,9 +8,7 @@ TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol bindin npm install @typespec/openapi3 ``` -## Emitter - -### Usage +## Usage 1. Via the command line @@ -35,15 +33,15 @@ options: option: value ``` -### Emitter options +## Emitter options -#### `file-type` +### `file-type` **Type:** `"yaml" | "json"` If the content should be serialized as YAML or JSON. Default 'yaml', it not specified infer from the `output-file` extension -#### `output-file` +### `output-file` **Type:** `string` @@ -76,27 +74,27 @@ Example Multiple service with versioning - `openapi.Org1.Service2.v1.0.yaml` - `openapi.Org1.Service2.v1.1.yaml` -#### `new-line` +### `new-line` **Type:** `"crlf" | "lf"` Set the newline character for emitting files. -#### `omit-unreachable-types` +### `omit-unreachable-types` **Type:** `boolean` Omit unreachable types. By default all types declared under the service namespace will be included. With this flag on only types references in an operation will be emitted. -#### `include-x-typespec-name` +### `include-x-typespec-name` **Type:** `"inline-only" | "never"` If the generated openapi types should have the `x-typespec-name` extension set with the name of the TypeSpec type that created it. This extension is meant for debugging and should not be depended on. -#### `safeint-strategy` +### `safeint-strategy` **Type:** `"double-int" | "int64"` diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md index 78f7d28da..04beab43e 100644 --- a/packages/protobuf/README.md +++ b/packages/protobuf/README.md @@ -8,9 +8,7 @@ TypeSpec library and emitter for Protobuf (gRPC) npm install @typespec/protobuf ``` -## Emitter - -### Usage +## Usage 1. Via the command line @@ -35,15 +33,15 @@ options: option: value ``` -### Emitter options +## Emitter options -#### `noEmit` +### `noEmit` **Type:** `boolean` If set to `true`, this emitter will not write any files. It will still validate the TypeSpec sources to ensure they are compatible with Protobuf, but the files will simply not be written to the output directory. -#### `omit-unreachable-types` +### `omit-unreachable-types` **Type:** `boolean` diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index f08916be9..bc0fc4776 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -65,35 +65,33 @@ function renderIndexFile(renderer: DocusaurusRenderer, refDoc: TypeSpecLibraryRe "import TabItem from '@theme/TabItem';", "", - section("Overview", [ - refDoc.description ?? [], - renderer.install(refDoc), - refDoc.emitter?.options ? section("Emitter usage", `[See documentation](./emitter.md)`) : [], + refDoc.description ?? [], + renderer.install(refDoc), + refDoc.emitter?.options ? section("Emitter usage", `[See documentation](./emitter.md)`) : [], - groupByNamespace(refDoc.namespaces, (namespace) => { - const content = []; + groupByNamespace(refDoc.namespaces, (namespace) => { + const content = []; - if (namespace.decorators.length > 0) { - content.push(section("Decorators", renderer.toc(namespace.decorators))); - } + if (namespace.decorators.length > 0) { + content.push(section("Decorators", renderer.toc(namespace.decorators))); + } - if (namespace.interfaces.length > 0) { - content.push(section("Interfaces", renderer.toc(namespace.interfaces))); - } + if (namespace.interfaces.length > 0) { + content.push(section("Interfaces", renderer.toc(namespace.interfaces))); + } - if (namespace.operations.length > 0) { - content.push(section("Operations", renderer.toc(namespace.operations))); - } + if (namespace.operations.length > 0) { + content.push(section("Operations", renderer.toc(namespace.operations))); + } - if (namespace.models.length > 0) { - content.push(section("Models", renderer.toc(namespace.models))); - } - return content; - }), - ]), + if (namespace.models.length > 0) { + content.push(section("Models", renderer.toc(namespace.models))); + } + return content; + }), ]; - return renderMarkdowDoc(content); + return renderMarkdowDoc(content, 2); } export type DecoratorRenderOptions = { @@ -117,8 +115,8 @@ export function renderDecoratorFile( "---", ]; - content.push(section(title, renderer.decoratorsSection(refDoc))); - return renderMarkdowDoc(content); + content.push(renderer.decoratorsSection(refDoc)); + return renderMarkdowDoc(content, 2); } function renderInterfacesFile( @@ -137,26 +135,24 @@ function renderInterfacesFile( ]; content.push( - section("Interfaces and Operations", [ - groupByNamespace(refDoc.namespaces, (namespace) => { - if (namespace.operations.length === 0 && namespace.interfaces.length === 0) { - return undefined; - } + groupByNamespace(refDoc.namespaces, (namespace) => { + if (namespace.operations.length === 0 && namespace.interfaces.length === 0) { + return undefined; + } - const content: MarkdownDoc = []; - for (const iface of namespace.interfaces) { - content.push(renderer.interface(iface), ""); - } + const content: MarkdownDoc = []; + for (const iface of namespace.interfaces) { + content.push(renderer.interface(iface), ""); + } - for (const operation of namespace.operations) { - content.push(renderer.operation(operation), ""); - } - return content; - }), - ]), + for (const operation of namespace.operations) { + content.push(renderer.operation(operation), ""); + } + return content; + }), ); - return renderMarkdowDoc(content); + return renderMarkdowDoc(content, 2); } export type DataTypeRenderOptions = { @@ -181,36 +177,33 @@ export function renderDataTypes( ]; content.push( - section( - "Data types", - groupByNamespace(refDoc.namespaces, (namespace) => { - const modelCount = - namespace.models.length + - namespace.enums.length + - namespace.unions.length + - namespace.scalars.length; - if (modelCount === 0) { - return undefined; - } - const content: MarkdownDoc = []; - for (const model of namespace.models) { - content.push(renderer.model(model), ""); - } - for (const e of namespace.enums) { - content.push(renderer.enum(e), ""); - } - for (const union of namespace.unions) { - content.push(renderer.union(union), ""); - } - for (const scalar of namespace.scalars) { - content.push(renderer.scalar(scalar), ""); - } - return content; - }), - ), + groupByNamespace(refDoc.namespaces, (namespace) => { + const modelCount = + namespace.models.length + + namespace.enums.length + + namespace.unions.length + + namespace.scalars.length; + if (modelCount === 0) { + return undefined; + } + const content: MarkdownDoc = []; + for (const model of namespace.models) { + content.push(renderer.model(model), ""); + } + for (const e of namespace.enums) { + content.push(renderer.enum(e), ""); + } + for (const union of namespace.unions) { + content.push(renderer.union(union), ""); + } + for (const scalar of namespace.scalars) { + content.push(renderer.scalar(scalar), ""); + } + return content; + }), ); - return renderMarkdowDoc(content); + return renderMarkdowDoc(content, 2); } function renderEmitter( @@ -229,7 +222,7 @@ function renderEmitter( renderer.emitterUsage(refDoc), ]; - return renderMarkdowDoc(content); + return renderMarkdowDoc(content, 2); } function renderLinter( renderer: DocusaurusRenderer, @@ -247,7 +240,7 @@ function renderLinter( renderer.linterUsage(refDoc), ]; - return renderMarkdowDoc(content); + return renderMarkdowDoc(content, 2); } export class DocusaurusRenderer extends MarkdownRenderer { diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 4528018ed..4a3a8761f 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -366,7 +366,7 @@ export class MarkdownRenderer { return []; } - return section("Emitter", [ + return [ section("Usage", [ "1. Via the command line", codeblock(`tsp compile . --emit=${refDoc.name}`, "bash"), @@ -379,7 +379,7 @@ export class MarkdownRenderer { ), ]), this.emitterOptions(refDoc.emitter.options), - ]); + ]; } emitterOptions(options: EmitterOptionRefDoc[]) { @@ -403,7 +403,7 @@ export class MarkdownRenderer { ? { extends: [refDoc.linter.ruleSets[0].name] } : { rules: {} }, }); - return section("Linter", [ + return [ section("Usage", ["Add the following in `tspconfig.yaml`:", codeblock(setupExample, "yaml")]), refDoc.linter.ruleSets ? section("RuleSets", [ @@ -412,7 +412,7 @@ export class MarkdownRenderer { ]) : [], section("Rules", this.linterRuleToc(refDoc.linter.rules)), - ]); + ]; } linterRuleToc(rules: LinterRuleRefDoc[]) {