@foxglove/schemas 0.2.0 → 0.5.0

package/src/generateJsonSchema.test.ts

@@ -8,7 +8,7 @@ describe("generateJsonSchema", () => {
   it("generates expected JSON Schema", () => {
     expect(generateJsonSchema(exampleMessage)).toMatchInlineSnapshot(`
       Object {
-        "$comment": "Generated from ExampleMessage by @foxglove/schemas",
+        "$comment": "Generated by https://github.com/foxglove/schemas",
         "description": "An example type",
         "properties": Object {
           "field_boolean": Object {
@@ -121,7 +121,7 @@ describe("generateJsonSchema", () => {
                 "title": "B",
               },
             ],
-            "title": "ExampleEnum: An example enum",
+            "title": "foxglove.ExampleEnum",
           },
           "field_enum_array": Object {
             "description": "An enum array field",
@@ -139,7 +139,7 @@ describe("generateJsonSchema", () => {
                   "title": "B",
                 },
               ],
-              "title": "ExampleEnum: An example enum",
+              "title": "foxglove.ExampleEnum",
             },
             "type": "array",
           },
@@ -164,7 +164,6 @@ describe("generateJsonSchema", () => {
             "type": "array",
           },
           "field_nested": Object {
-            "$comment": "Generated from NestedMessage by @foxglove/schemas",
             "description": "A nested field",
             "properties": Object {
               "field_enum": Object {
@@ -173,7 +172,7 @@ describe("generateJsonSchema", () => {
                 "type": "integer",
               },
             },
-            "title": "NestedMessage",
+            "title": "foxglove.NestedMessage",
             "type": "object",
           },
           "field_nested_array": Object {
@@ -184,7 +183,6 @@ describe("generateJsonSchema", () => {
       long
       description",
             "items": Object {
-              "$comment": "Generated from NestedMessage by @foxglove/schemas",
               "description": "An example nested message",
               "properties": Object {
                 "field_enum": Object {
@@ -193,7 +191,7 @@ describe("generateJsonSchema", () => {
                   "type": "integer",
                 },
               },
-              "title": "NestedMessage",
+              "title": "foxglove.NestedMessage",
               "type": "object",
             },
             "type": "array",
@@ -298,7 +296,7 @@ describe("generateJsonSchema", () => {
             "type": "array",
           },
         },
-        "title": "ExampleMessage",
+        "title": "foxglove.ExampleMessage",
         "type": "object",
       }
     `);

package/src/generateJsonSchema.ts

@@ -45,10 +45,11 @@ export function generateJsonSchema(schema: FoxgloveMessageSchema): Record<string
         break;
       case "nested":
         fieldType = generateJsonSchema(field.type.schema);
+        delete fieldType.$comment;
         break;
       case "enum":
         fieldType = {
-          title: `${field.type.enum.name}: ${field.type.enum.description}`,
+          title: `foxglove.${field.type.enum.name}`,
           description: field.description,
           oneOf: field.type.enum.values.map(({ name, value, description }) => ({
             title: name,
@@ -73,9 +74,9 @@ export function generateJsonSchema(schema: FoxgloveMessageSchema): Record<string
   }
 
   return {
-    $comment: `Generated from ${schema.name} by @foxglove/schemas`,
-    title: schema.name,
+    title: `foxglove.${schema.name}`,
     description: schema.description,
+    $comment: "Generated by https://github.com/foxglove/schemas",
     type: "object",
     properties,
   };

package/src/generateMarkdown.ts

@@ -0,0 +1,88 @@
+import { FoxgloveEnumSchema, FoxgloveMessageSchema } from "./types";
+
+export function generateMarkdown(
+  schemas: Iterable<FoxgloveMessageSchema>,
+  enums: Iterable<FoxgloveEnumSchema>,
+): string {
+  const sortedSchemas = [...schemas].sort((a, b) => a.name.localeCompare(b.name));
+  const sortedEnums = [...enums].sort((a, b) => a.name.localeCompare(b.name));
+
+  return [
+    `\
+# Foxglove schemas
+
+See [Foxglove Schemas documentation](https://foxglove.dev/docs/studio/messages).
+
+All schemas are generated from [schemas.ts](/src/schemas.ts).`,
+
+    "## Contents",
+
+    [
+      ...sortedEnums.map(({ name }) => `- [enum ${name}](#enum-${name.toLowerCase()})`),
+      ...sortedSchemas.map(({ name }) => `- [${name}](#${name.toLowerCase()})`),
+    ].join("\n"),
+    "----",
+    sortedEnums.map(
+      (enumSchema) => `\
+## enum ${enumSchema.name}
+
+${enumSchema.description}
+
+name | value | description
+---- | ----- | -----------
+${enumSchema.values
+  .map((value) => `\`${value.name}\` | ${value.value} | ${value.description ?? ""}`)
+  .join("\n")}
+
+`,
+    ),
+    ...sortedSchemas.map(
+      (schema) => `\
+## ${schema.name}
+
+${schema.description}
+
+<table>
+  <tr>
+    <th>field</th>
+    <th>type</th>
+    <th>description</th>
+  </tr>
+${schema.fields
+  .map((field) => {
+    const arraySuffix =
+      typeof field.array === "number" ? `[${field.array}]` : field.array === true ? "[]" : "";
+    let type: string;
+    switch (field.type.type) {
+      case "enum":
+        type = `[enum ${field.type.enum.name}](#enum-${field.type.enum.name.toLowerCase()})`;
+        break;
+      case "nested":
+        type = `[${field.type.schema.name}](#${field.type.schema.name.toLowerCase()})`;
+        break;
+      case "primitive":
+        type = field.type.name;
+        break;
+    }
+    return `\
+<tr>
+<td><code>${field.name}</code></td>
+<td>
+
+${type}${arraySuffix}
+
+</td>
+<td>
+
+${field.description}
+
+</td>
+</tr>`;
+  })
+  .join("\n")}
+</table>`,
+    ),
+  ]
+    .flat()
+    .join("\n\n");
+}

package/src/generateProto.test.ts

@@ -7,7 +7,7 @@ import { exampleEnum, exampleMessage } from "./testFixtures";
 describe("generateProto", () => {
   it("generates .proto files", () => {
     expect(generateProto(exampleMessage, [exampleEnum])).toMatchInlineSnapshot(`
-      "// Generated from ExampleMessage by @foxglove/schemas
+      "// Generated by https://github.com/foxglove/schemas
 
       syntax = \\"proto3\\";
 

package/src/generateProto.ts

@@ -80,7 +80,7 @@ export function generateProto(
   )}${fields.join("\n\n")}\n}`;
 
   const outputSections = [
-    `// Generated from ${schema.name} by @foxglove/schemas`,
+    `// Generated by https://github.com/foxglove/schemas`,
     'syntax = "proto3";',
 
     Array.from(imports)