Update emitter docs to include configuration examples (#4112)

For a TypeSpec beginner, it may be difficult to understand how to configure or format tspconfig.yaml to tweak the different options available. Adding a basic example should help folks get started.
microsoft · Aug 8, 2024 · dda9db6 · dda9db6
1 parent 1455928
commit dda9db6
Show file tree

Hide file tree

Showing 7 changed files with 65 additions and 0 deletions.
diff --git a/docs/emitters/json-schema/reference/emitter.md b/docs/emitters/json-schema/reference/emitter.md
@@ -21,6 +21,16 @@ emit:
   - "@typespec/json-schema"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/json-schema"
+options:
+  "@typespec/json-schema":
+    option: value
+```
+
 ## Emitter options
 
 ### `file-type`

diff --git a/docs/emitters/openapi3/reference/emitter.md b/docs/emitters/openapi3/reference/emitter.md
@@ -21,6 +21,16 @@ emit:
   - "@typespec/openapi3"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/openapi3"
+options:
+  "@typespec/openapi3":
+    option: value
+```
+
 ## Emitter options
 
 ### `file-type`

diff --git a/docs/emitters/protobuf/reference/emitter.md b/docs/emitters/protobuf/reference/emitter.md
@@ -21,6 +21,16 @@ emit:
   - "@typespec/protobuf"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/protobuf"
+options:
+  "@typespec/protobuf":
+    option: value
+```
+
 ## Emitter options
 
 ### `noEmit`

diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md
@@ -43,6 +43,16 @@ emit:
   - "@typespec/json-schema"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/json-schema"
+options:
+  "@typespec/json-schema":
+    option: value
+```
+
 ### Emitter options
 
 #### `file-type`

diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md
@@ -25,6 +25,16 @@ emit:
   - "@typespec/openapi3"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/openapi3"
+options:
+  "@typespec/openapi3":
+    option: value
+```
+
 ### Emitter options
 
 #### `file-type`

diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md
@@ -25,6 +25,16 @@ emit:
   - "@typespec/protobuf"
 ```
 
+The config can be extended with options as follows:
+
+```yaml
+emit:
+  - "@typespec/protobuf"
+options:
+  "@typespec/protobuf":
+    option: value
+```
+
 ### Emitter options
 
 #### `noEmit`

diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts
@@ -372,6 +372,11 @@ export class MarkdownRenderer {
         codeblock(`tsp compile . --emit=${refDoc.name}`, "bash"),
         "2. Via the config",
         codeblock(`emit:\n  - "${refDoc.name}" `, "yaml"),
+        "The config can be extended with options as follows:",
+        codeblock(
+          `emit:\n  - "${refDoc.name}"\noptions:\n  "${refDoc.name}":\n    option: value`,
+          "yaml"
+        ),
       ]),
       this.emitterOptions(refDoc.emitter.options),
     ]);