Merge pull request #11923 from RoadieHQ/add-protoc-gen-doc-support

Add protoc gen doc support

plugins/api-docs-module-protoc-gen-doc/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/api-docs-module-protoc-gen-doc/README.md

@@ -0,0 +1,56 @@
+# @backstage/plugin-api-docs-module-protoc-gen-doc
+
+This package contains ApiDefinitionWidgets for the following projects:
+
+- [grpc-docs](https://github.com/gendocu-com/grpc-docs)
+
+## Setup
+
+```
+yarn add @backstage/plugin-api-docs-module-protoc-gen-doc
+```
+
+## Add the GrpcDocsApiWidget to your apis
+
+Add the widget to your `apiDocsConfigRef`.
+
+```ts
+import { grpcDocsApiWidget } from '@backstage/plugin-api-docs-module-protoc-gen-doc';
+// packages/app/apis.ts
+export const apis: AnyApiFactory[] = [
+  createApiFactory({
+    api: apiDocsConfigRef,
+    deps: {},
+    factory: () => {
+      // load the default widgets
+      const definitionWidgets = defaultDefinitionWidgets();
+      // add the grpc-docs api widget to the definition widgets
+      definitionWidgets.push(grpcDocsApiWidget);
+      return {
+        getApiDefinitionWidget: (apiEntity: ApiEntity) => {
+          // find the widget for the type of api entity
+          return definitionWidgets.find(d => d.type === apiEntity.spec.type);
+        },
+      };
+    },
+  }),
+];
+```
+
+### Set the type in your api entities
+
+This widget will render the generated `protoc-gen-doc` descriptors with the `grpc-docs` package. For this make sure you use the `grpc-docs` as the type in the API catalog file.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: hello-world
+  description: Hello World example for gRPC
+spec:
+  type: grpc-docs
+  lifecycle: deprecated
+  owner: foo
+  definition:
+    $text: https://fetch-my-json.com/awesome-resource.json
+```

plugins/api-docs-module-protoc-gen-doc/api-report.md

@@ -0,0 +1,14 @@
+## API Report File for "@backstage/plugin-api-docs-module-protoc-gen-doc"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+/// <reference types="react" />
+
+// @public (undocumented)
+export const grpcDocsApiWidget: {
+  type: string;
+  title: string;
+  component: (definition: string) => JSX.Element;
+};
+```

plugins/api-docs-module-protoc-gen-doc/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@backstage/plugin-api-docs-module-protoc-gen-doc",
+  "description": "Additional functionalities for the api-docs plugin that renders the output of the protoc-gen-doc",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "frontend-plugin-module"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/api-docs-module-protoc-gen-doc"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "grpc-docs": "^1.1.2"
+  },
+  "peerDependencies": {
+    "react": "^16.13.1 || ^17.0.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.17.2-next.0",
+    "@testing-library/jest-dom": "^5.16.4",
+    "@types/react": "^16.13.1 || ^17.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/api-docs-module-protoc-gen-doc/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Package encapsulating utilities to be shared by frontend TechDocs plugins.
+ *
+ * @packageDocumentation
+ */
+
+export { grpcDocsApiWidget } from './widgets';

plugins/api-docs-module-protoc-gen-doc/src/setupTests.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import '@testing-library/jest-dom';

plugins/api-docs-module-protoc-gen-doc/src/widgets.tsx

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+import { GRPCSelfGeneratedAPIReference } from 'grpc-docs';
+
+/**
+ * @public
+ */
+export const grpcDocsApiWidget = {
+  type: 'grpc-docs',
+  title: 'gRPC',
+  component: (definition: string) => (
+    <GRPCSelfGeneratedAPIReference definition={definition || ''} />
+  ),
+};