From 58bd612c17c8eae68755c228518bfd65001133f5 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 10 Oct 2024 10:40:05 -0700 Subject: [PATCH] Remove duplicate title heading for generated docs (#4666) --- docs/emitters/json-schema/guide.md | 2 - .../json-schema/reference/data-types.md | 2 - .../json-schema/reference/decorators.md | 2 - .../emitters/json-schema/reference/emitter.md | 2 - docs/emitters/json-schema/reference/index.mdx | 2 - docs/emitters/openapi3/cli.md | 2 - docs/emitters/openapi3/diagnostics.md | 2 - docs/emitters/openapi3/openapi.md | 2 - .../emitters/openapi3/reference/decorators.md | 2 - docs/emitters/openapi3/reference/emitter.md | 2 - docs/emitters/openapi3/reference/index.mdx | 2 - docs/emitters/protobuf/guide.md | 2 - .../emitters/protobuf/reference/data-types.md | 2 - .../emitters/protobuf/reference/decorators.md | 2 - docs/emitters/protobuf/reference/emitter.md | 2 - docs/emitters/protobuf/reference/index.mdx | 2 - docs/extending-typespec/basics.md | 2 - docs/extending-typespec/create-decorators.md | 2 - docs/extending-typespec/emitter-framework.md | 2 - .../emitter-metadata-handling.md | 2 - docs/extending-typespec/emitters-basics.md | 2 - docs/extending-typespec/linters.md | 2 - .../writing-scaffolding-template.md | 2 - .../01-setup-basic-syntax.md | 2 - .../02-operations-responses.md | 2 - .../03-handling-errors.md | 2 - .../04-common-parameters.md | 2 - .../getting-started-rest/05-authentication.md | 2 - .../getting-started-rest/06-versioning.md | 2 - .../07-custom-response-models.md | 2 - .../getting-started-rest/08-conclusion.md | 2 - docs/getting-started/getting-started.md | 2 - .../typespec-for-openapi-dev.md | 2 - docs/handbook/cli.md | 2 - docs/handbook/configuration/configuration.md | 2 - docs/handbook/configuration/tracing.md | 2 - docs/handbook/faq.md | 2 - docs/handbook/formatter.md | 2 - docs/handbook/releases.md | 2 - docs/handbook/style-guide.md | 2 - docs/introduction/installation.md | 2 - docs/language-basics/alias.md | 2 - docs/language-basics/built-in-types.md | 2 - docs/language-basics/decorators.md | 2 - docs/language-basics/documentation.md | 6 +- docs/language-basics/enums.md | 2 - docs/language-basics/identifiers.md | 2 - docs/language-basics/imports.md | 2 - docs/language-basics/interfaces.md | 2 - docs/language-basics/intersections.md | 2 - docs/language-basics/models.md | 2 - docs/language-basics/namespaces.md | 2 - docs/language-basics/operations.md | 2 - docs/language-basics/overview.md | 2 - docs/language-basics/scalars.md | 2 - docs/language-basics/templates.md | 2 - docs/language-basics/type-literals.md | 2 - docs/language-basics/type-relations.md | 2 - docs/language-basics/unions.md | 2 - docs/language-basics/values.md | 2 - docs/libraries/events/reference/decorators.md | 2 - docs/libraries/events/reference/index.mdx | 2 - .../reference/emitter.md | 2 +- .../reference/index.mdx | 2 +- docs/libraries/http/authentication.md | 2 - docs/libraries/http/examples.md | 2 - docs/libraries/http/operations.md | 2 - docs/libraries/http/reference/data-types.md | 2 - docs/libraries/http/reference/decorators.md | 2 - docs/libraries/http/reference/index.mdx | 2 - docs/libraries/http/reference/linter.md | 2 - .../libraries/openapi/reference/data-types.md | 2 - .../libraries/openapi/reference/decorators.md | 2 - docs/libraries/openapi/reference/index.mdx | 2 - docs/libraries/rest/reference/data-types.md | 2 - docs/libraries/rest/reference/decorators.md | 2 - docs/libraries/rest/reference/index.mdx | 2 - docs/libraries/rest/reference/interfaces.md | 2 - docs/libraries/rest/resource-routing.md | 2 - docs/libraries/sse/reference/data-types.md | 2 - docs/libraries/sse/reference/decorators.md | 2 - docs/libraries/sse/reference/index.mdx | 2 - docs/libraries/stream/reference/data-types.md | 2 +- docs/libraries/stream/reference/decorators.md | 2 +- docs/libraries/stream/reference/index.mdx | 2 +- .../libraries/streams/reference/data-types.md | 2 - .../libraries/streams/reference/decorators.md | 2 - docs/libraries/streams/reference/index.mdx | 2 - .../versioning/reference/decorators.md | 2 - docs/libraries/versioning/reference/index.mdx | 2 - docs/libraries/xml/guide.md | 2 - docs/libraries/xml/reference/decorators.md | 2 - docs/libraries/xml/reference/index.mdx | 2 - docs/release-notes/release-2022-07-08.md | 2 - docs/release-notes/release-2022-08-10.md | 2 - docs/release-notes/release-2022-09-07.md | 2 - docs/release-notes/release-2022-10-12.md | 2 - docs/release-notes/release-2022-12-07.md | 2 - docs/release-notes/release-2023-01-12.md | 2 - docs/release-notes/release-2023-02-07.md | 2 - docs/release-notes/release-2023-03-13.md | 2 - docs/release-notes/release-2023-04-11.md | 2 - docs/release-notes/release-2023-05-10.md | 2 - docs/release-notes/release-2023-06-06.md | 2 - docs/release-notes/release-2023-07-11.md | 2 - docs/release-notes/release-2023-08-08.md | 2 - docs/release-notes/release-2023-09-12.md | 2 - docs/release-notes/release-2023-10-11.md | 2 - docs/release-notes/release-2023-11-07.md | 2 - docs/release-notes/release-2023-12-06.md | 2 - docs/release-notes/release-2024-01-23.md | 2 - docs/release-notes/release-2024-02-06.md | 2 - docs/release-notes/release-2024-03-05.md | 2 - docs/release-notes/release-2024-04-02.md | 2 - docs/release-notes/release-2024-05-07.md | 2 - docs/standard-library/built-in-data-types.md | 1 - docs/standard-library/built-in-decorators.md | 1 - docs/standard-library/examples.md | 2 - .../docs/rules/call-decorator.md | 2 - .../generator/docs/cadl-ranch.md | 2 - .../generator/docs/generate/options.md | 2 - packages/http/README.md | 8 +- packages/json-schema/README.md | 16 +- packages/openapi3/README.md | 18 +-- packages/protobuf/README.md | 10 +- .../tspd/src/ref-doc/emitters/docusaurus.ts | 147 +++++++++--------- .../tspd/src/ref-doc/emitters/markdown.ts | 8 +- 127 files changed, 103 insertions(+), 348 deletions(-) diff --git a/docs/emitters/json-schema/guide.md b/docs/emitters/json-schema/guide.md index 6636c477a5..de277af1c2 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 00d426ca02..27a1a59fb8 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 2d7f756e48..fc67e9a527 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 fad9906679..fccf19c6f8 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 ce0f343fb0..13d448cb90 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 3f8beaefe8..2629af830f 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 847b7ef8a8..af1aae874d 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 1a04c8b798..b3a8358836 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 c377176b73..c057a1ad57 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 53827c1e33..7b2816e705 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 63b200c638..b1836a03fd 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 b2a01305a2..a02299cd71 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 1888cdb2e2..7c7a413a01 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 1491b78bf6..551e61e91e 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 b9c8fc2454..5c0ad2c42a 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 3914200c66..5134f93796 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 4deefa490b..c1fcc3b640 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 3c4986ea2a..a620b67fc9 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 32f8a966b1..b2490de393 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 70493280e7..82b068426b 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 c7ea724509..d92540d37f 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 67ccd8ef44..3d3af314e4 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 62de15cbdd..8a5571e5cd 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 e7ade3d7c5..a9dfdcd2e7 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 8a840aa620..dd370f42f8 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 7a0e868541..d92d05e4cc 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 066fecef7a..61e7493d16 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 4365b93e7e..61b1111a14 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 d0fcf48731..e79f0ea3f2 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 ecd507114b..86c7245e1d 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 4d0071cd46..5a9fcb8755 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 46f112b1e5..2a57a3236b 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 a7c5b42d06..949bff8788 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 094437a695..9e49446a7a 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 d448452635..367f502bef 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 89eaaa8da0..9416d4944c 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 196f25cc0a..f186c8106b 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 a4363449ae..2a86352d83 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 69b00547fb..04906a2f0c 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 9c7d0e66c4..b009ccdf9e 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 969f8ef6d6..07f197c129 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 d010112614..ed29ec9ee6 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 d70a40cf23..380c4071fd 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 aa57714ad5..2cdeb3c05f 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 52e5149dda..6f6f246569 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 7abb25dfdc..829b5262f2 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 2f4d0e95c9..5de21c9404 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 7ec9267e19..de6ff9462e 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 01452f2c9e..28df25ffd6 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 89e6c36f9c..6023eaf451 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 d591709426..c3ad0749d5 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 5ac0a71022..6f4d6baa1b 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 4f774eeafb..c503e6d835 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 bf4a611ad5..0ab9329cb7 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 93a97f2f55..fbb30c6ed3 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 857b93de8d..65c087bc32 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 2de0abad55..7873ecb5f4 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 aa1ef1e8e7..217b66b997 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 9c1014c0f5..9050918896 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 4bed4774f0..8b3109d2c1 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 69772a8bbd..302ea7e5a3 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 514d08760f..5ca619d1c4 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 48a590d5ef..a1299e9cd6 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 f49d39fb19..51d1c36d51 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 04a7a9fa09..4a1779f401 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 f6b0700c9d..9c4cd7e5f8 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 9071328c5d..dcc4d085f6 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 549e8fc88d..e36be1cd43 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 a55f429071..d4f2a49f0e 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 352ea8d952..865df0b23c 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 e36573415f..5440e045d1 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 04831f5d81..043a4ec50c 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 90b23016bb..be7cf18311 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 7626cf0bda..6510dee917 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 6b1dcd5d1e..519042ec07 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 39ec842b5a..c9862cab6b 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 158097c6d3..a30a6786c3 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 14876462be..c08054e132 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 a76d4b6070..69be7e07f3 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 d322877397..69f4dbb19f 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 a92b00db99..072c6d53bb 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 fd60078eb0..298547e884 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 6b52f0434f..45b143c396 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 7baec7a7bb..13043a8482 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 854a1d24a3..a022277a64 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 6b52f0434f..646175c4ed 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 7baec7a7bb..ebca14470b 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 854a1d24a3..840377595b 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 536aace65f..7630dff3dd 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 1a9826b034..ca9ce02cb3 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 f7860abe97..a13d302aa9 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 d1917fce4d..c13536f91f 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 6b1f7600a9..898bc8894a 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 84142599b3..62ec453131 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 8e58c40624..add8efbe04 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 2d65e49e47..08eb6745b0 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 113c120759..5af411ad4f 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 de2cf660e8..cb2c28b34a 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 534e6c1c7b..fd9989e5ea 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 b093ca047a..9999ad5cad 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 843e0c58f9..2a0f6c3531 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 6f0fa53770..289bd73662 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 249a9b0777..3d85e38e4f 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 d8df3c9510..5e297fd89b 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 b03fbd7e91..e90e1096ea 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 2258de93d2..3402ffee54 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 ba0bf66744..7e8e1cad8f 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 8bde62a9bc..f61e02b867 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 7f4de3662c..242a848cbe 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 b68f00beb4..b578f787d1 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 1c21054958..1011836dcb 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 0ff2d18616..701e96b09a 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 c6ce8723e0..7e9a7ae73b 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 590557a3f6..b1149f7ede 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 0fcec11b0b..65f9bfa592 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 ae1639782f..dfa2583878 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 d30994aa58..6ea1cc138d 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 7ee382b624..fe85220569 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 4be26e7bab..b4d98d5050 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 142f47a1eb..bf088c2473 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 a54a957948..58a1f4c302 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 837b28a6ed..f96ba37e1a 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 ccc84c5429..592b9c6735 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 6427230ab7..cd139f049b 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 78f7d28da0..04beab43e8 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 f08916be91..bc0fc47769 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)`) : [], - - groupByNamespace(refDoc.namespaces, (namespace) => { - const content = []; - - 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.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; - }), - ]), + refDoc.description ?? [], + renderer.install(refDoc), + refDoc.emitter?.options ? section("Emitter usage", `[See documentation](./emitter.md)`) : [], + + groupByNamespace(refDoc.namespaces, (namespace) => { + const content = []; + + 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.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; + }), ]; - 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; - } - - 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; - }), - ]), + 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), ""); + } + + 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 4528018ed8..4a3a8761f6 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[]) {