@foxglove/schemas 0.1.2 → 0.4.0

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)

package/src/generateRos.test.ts

@@ -8,7 +8,446 @@ import {
 import { foxgloveMessageSchemas } from "./schemas";
 import { exampleMessageWithoutArrayOfBytes } from "./testFixtures";
 
-describe("generateRosMsgFiles", () => {
+describe("generateRosMsgDefinition", () => {
+  it("generates msg definition description for ROS 1", () => {
+    expect(generateRosMsgDefinition(exampleMessageWithoutArrayOfBytes, { rosVersion: 1 }))
+      .toMatchInlineSnapshot(`
+      Object {
+        "description": "An example type",
+        "fields": Array [
+          Object {
+            "arrayLength": undefined,
+            "description": "duration field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_duration",
+            "type": "duration",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "time field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_time",
+            "type": "time",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "boolean field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_boolean",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "bytes field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_bytes",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "float64 field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_float64",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "uint32 field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_uint32",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "string field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_string",
+            "type": "string",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "duration array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_duration_array",
+            "type": "duration",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "time array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_time_array",
+            "type": "time",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "boolean array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_boolean_array",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "float64 array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_float64_array",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "uint32 array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_uint32_array",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "string array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_string_array",
+            "type": "string",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "duration fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_duration_fixed_array",
+            "type": "duration",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "time fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_time_fixed_array",
+            "type": "time",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "boolean fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_boolean_fixed_array",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "float64 fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_float64_fixed_array",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "uint32 fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_uint32_fixed_array",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "string fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_string_fixed_array",
+            "type": "string",
+          },
+          Object {
+            "description": "Value A",
+            "isConstant": true,
+            "name": "A",
+            "type": "uint8",
+            "value": 1,
+            "valueText": "1",
+          },
+          Object {
+            "description": "Value B",
+            "isConstant": true,
+            "name": "B",
+            "type": "uint8",
+            "value": 2,
+            "valueText": "2",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "An enum field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_enum",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "An enum array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_enum_array",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "A nested field",
+            "isArray": false,
+            "isComplex": true,
+            "name": "field_nested",
+            "type": "foxglove_msgs/NestedMessage",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "A nested array field
+      With
+      a
+      very
+      long
+      description",
+            "isArray": true,
+            "isComplex": true,
+            "name": "field_nested_array",
+            "type": "foxglove_msgs/NestedMessage",
+          },
+        ],
+        "originalName": "ExampleMessage",
+        "rosFullInterfaceName": "foxglove_msgs/ExampleMessage",
+        "rosMsgInterfaceName": "foxglove_msgs/ExampleMessage",
+      }
+    `);
+  });
+  it("generates msg definition description for ROS 2", () => {
+    expect(generateRosMsgDefinition(exampleMessageWithoutArrayOfBytes, { rosVersion: 2 }))
+      .toMatchInlineSnapshot(`
+      Object {
+        "description": "An example type",
+        "fields": Array [
+          Object {
+            "arrayLength": undefined,
+            "description": "duration field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_duration",
+            "type": "builtin_interfaces/Duration",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "time field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_time",
+            "type": "builtin_interfaces/Time",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "boolean field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_boolean",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "bytes field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_bytes",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "float64 field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_float64",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "uint32 field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_uint32",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "string field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_string",
+            "type": "string",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "duration array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_duration_array",
+            "type": "builtin_interfaces/Duration",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "time array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_time_array",
+            "type": "builtin_interfaces/Time",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "boolean array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_boolean_array",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "float64 array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_float64_array",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "uint32 array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_uint32_array",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "string array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_string_array",
+            "type": "string",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "duration fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_duration_fixed_array",
+            "type": "builtin_interfaces/Duration",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "time fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_time_fixed_array",
+            "type": "builtin_interfaces/Time",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "boolean fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_boolean_fixed_array",
+            "type": "bool",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "float64 fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_float64_fixed_array",
+            "type": "float64",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "uint32 fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_uint32_fixed_array",
+            "type": "uint32",
+          },
+          Object {
+            "arrayLength": 3,
+            "description": "string fixed-length array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_string_fixed_array",
+            "type": "string",
+          },
+          Object {
+            "description": "Value A",
+            "isConstant": true,
+            "name": "A",
+            "type": "uint8",
+            "value": 1,
+            "valueText": "1",
+          },
+          Object {
+            "description": "Value B",
+            "isConstant": true,
+            "name": "B",
+            "type": "uint8",
+            "value": 2,
+            "valueText": "2",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "An enum field",
+            "isArray": false,
+            "isComplex": false,
+            "name": "field_enum",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "An enum array field",
+            "isArray": true,
+            "isComplex": false,
+            "name": "field_enum_array",
+            "type": "uint8",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "A nested field",
+            "isArray": false,
+            "isComplex": true,
+            "name": "field_nested",
+            "type": "foxglove_msgs/NestedMessage",
+          },
+          Object {
+            "arrayLength": undefined,
+            "description": "A nested array field
+      With
+      a
+      very
+      long
+      description",
+            "isArray": true,
+            "isComplex": true,
+            "name": "field_nested_array",
+            "type": "foxglove_msgs/NestedMessage",
+          },
+        ],
+        "originalName": "ExampleMessage",
+        "rosFullInterfaceName": "foxglove_msgs/msg/ExampleMessage",
+        "rosMsgInterfaceName": "foxglove_msgs/ExampleMessage",
+      }
+    `);
+  });
+});
+
+describe("generateRosMsg", () => {
   it("generates msg file for ROS 1", () => {
     expect(
       generateRosMsg(
@@ -17,7 +456,10 @@ describe("generateRosMsgFiles", () => {
         }),
       ),
     ).toMatchInlineSnapshot(`
-      "# Generated from ExampleMessage by @foxglove/schemas
+      "# foxglove_msgs/ExampleMessage
+      # An example type
+
+      # Generated by https://github.com/foxglove/schemas
 
       # duration field
       duration field_duration
@@ -110,7 +552,10 @@ describe("generateRosMsgFiles", () => {
         }),
       ),
     ).toMatchInlineSnapshot(`
-      "# Generated from ExampleMessage by @foxglove/schemas
+      "# foxglove_msgs/msg/ExampleMessage
+      # An example type
+
+      # Generated by https://github.com/foxglove/schemas
 
       # duration field
       builtin_interfaces/Duration field_duration
@@ -202,7 +647,10 @@ describe("generateRosMsgMergedSchema", () => {
       rosVersion: 1,
     });
     expect(mergedSchema).toMatchInlineSnapshot(`
-      "# Generated from ExampleMessage by @foxglove/schemas
+      "# foxglove_msgs/ExampleMessage
+      # An example type
+
+      # Generated by https://github.com/foxglove/schemas
 
       # duration field
       duration field_duration
@@ -285,7 +733,10 @@ describe("generateRosMsgMergedSchema", () => {
       foxglove_msgs/NestedMessage[] field_nested_array
       ================================================================================
       MSG: foxglove_msgs/NestedMessage
-      # Generated from NestedMessage by @foxglove/schemas
+      # foxglove_msgs/NestedMessage
+      # An example nested message
+
+      # Generated by https://github.com/foxglove/schemas
 
       # An enum field
       uint32 field_enum
@@ -476,7 +927,10 @@ describe("generateRosMsgMergedSchema", () => {
       rosVersion: 2,
     });
     expect(mergedSchema).toMatchInlineSnapshot(`
-      "# Generated from ExampleMessage by @foxglove/schemas
+      "# foxglove_msgs/msg/ExampleMessage
+      # An example type
+
+      # Generated by https://github.com/foxglove/schemas
 
       # duration field
       builtin_interfaces/Duration field_duration
@@ -559,7 +1013,10 @@ describe("generateRosMsgMergedSchema", () => {
       foxglove_msgs/NestedMessage[] field_nested_array
       ================================================================================
       MSG: foxglove_msgs/NestedMessage
-      # Generated from NestedMessage by @foxglove/schemas
+      # foxglove_msgs/msg/NestedMessage
+      # An example nested message
+
+      # Generated by https://github.com/foxglove/schemas
 
       # An enum field
       uint32 field_enum