From 19c0db60aa471e50bd4d10daf7e9ee7d275cdfd5 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Mon, 14 Mar 2022 16:26:56 +0100 Subject: [PATCH] Initial package to encapsulate the TechDocs addon framework. Signed-off-by: Eric Peterson --- plugins/techdocs-addons/.eslintrc.js | 1 + plugins/techdocs-addons/README.md | 5 ++ plugins/techdocs-addons/api-report.md | 24 ++++++++++ plugins/techdocs-addons/package.json | 33 +++++++++++++ plugins/techdocs-addons/src/index.ts | 23 +++++++++ plugins/techdocs-addons/src/types.ts | 69 +++++++++++++++++++++++++++ scripts/api-extractor.ts | 3 +- 7 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 plugins/techdocs-addons/.eslintrc.js create mode 100644 plugins/techdocs-addons/README.md create mode 100644 plugins/techdocs-addons/api-report.md create mode 100644 plugins/techdocs-addons/package.json create mode 100644 plugins/techdocs-addons/src/index.ts create mode 100644 plugins/techdocs-addons/src/types.ts diff --git a/plugins/techdocs-addons/.eslintrc.js b/plugins/techdocs-addons/.eslintrc.js new file mode 100644 index 0000000000..e2a53a6ad2 --- /dev/null +++ b/plugins/techdocs-addons/.eslintrc.js @@ -0,0 +1 @@ +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/plugins/techdocs-addons/README.md b/plugins/techdocs-addons/README.md new file mode 100644 index 0000000000..b97a8d583d --- /dev/null +++ b/plugins/techdocs-addons/README.md @@ -0,0 +1,5 @@ +# @backstage/plugin-techdocs-addons + +Package encapsulating the TechDocs Addons framework. + +todo(backstage/techdocs-core): Fill in with real documentation! diff --git a/plugins/techdocs-addons/api-report.md b/plugins/techdocs-addons/api-report.md new file mode 100644 index 0000000000..e14ea6112c --- /dev/null +++ b/plugins/techdocs-addons/api-report.md @@ -0,0 +1,24 @@ +## API Report File for "@backstage/plugin-techdocs-addons" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +import { ComponentType } from 'react'; + +// @public +export enum TechDocsAddonLocations { + COMPONENT = 'component', + CONTENT = 'content', + HEADER = 'header', + PRIMARY_SIDEBAR = 'primary sidebar', + SECONDARY_SIDEBAR = 'secondary sidebar', + SUBHEADER = 'subheader', +} + +// @public +export type TechDocsAddonOptions = { + name: string; + location: TechDocsAddonLocations; + component: ComponentType; +}; +``` diff --git a/plugins/techdocs-addons/package.json b/plugins/techdocs-addons/package.json new file mode 100644 index 0000000000..4df0488689 --- /dev/null +++ b/plugins/techdocs-addons/package.json @@ -0,0 +1,33 @@ +{ + "name": "@backstage/plugin-techdocs-addons", + "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" + }, + "scripts": { + "start": "backstage-cli package start", + "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": {}, + "peerDependencies": { + "@types/react": "^16.13.1 || ^17.0.0", + "react": "^16.13.1 || ^17.0.0" + }, + "devDependencies": {}, + "files": [ + "dist" + ] +} diff --git a/plugins/techdocs-addons/src/index.ts b/plugins/techdocs-addons/src/index.ts new file mode 100644 index 0000000000..715da10e20 --- /dev/null +++ b/plugins/techdocs-addons/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 the TechDocs Addon framework. + * + * @packageDocumentation + */ + +export type { TechDocsAddonLocations, TechDocsAddonOptions } from './types'; diff --git a/plugins/techdocs-addons/src/types.ts b/plugins/techdocs-addons/src/types.ts new file mode 100644 index 0000000000..584d2229b3 --- /dev/null +++ b/plugins/techdocs-addons/src/types.ts @@ -0,0 +1,69 @@ +/* + * 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 { ComponentType } from 'react'; + +/** + * Locations for which TechDocs addons may be declared and rendered. + * @public + */ +export enum TechDocsAddonLocations { + /** + * These addons fill up the header from the right, on the same line as the + * title. + */ + HEADER = 'header', + + /** + * These addons appear below the header and above all content; tooling addons + * can be inserted for convenience. + */ + SUBHEADER = 'subheader', + + /** + * These addons appear left of the content and above the navigation. + */ + PRIMARY_SIDEBAR = 'primary sidebar', + + /** + * These addons appear right of the content and above the table of contents. + */ + SECONDARY_SIDEBAR = 'secondary sidebar', + + /** + * A virtual location which allows mutation of all content within the shadow + * root by transforming DOM nodes. These addons should return null on render. + */ + CONTENT = 'content', + + /** + * A virtual location allowing an instance of the addon to be rendered for + * every HTML node with the same tag name as the addon name in the markdown + * content. If no reference is made, no instance will be rendered. Works like + * regular React components, just being accessible from markdown. + */ + COMPONENT = 'component', +} + +/** + * Options for creating a TechDocs addon. + * @public + */ +export type TechDocsAddonOptions = { + name: string; + location: TechDocsAddonLocations; + component: ComponentType; +}; diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 79f1f1eeb4..19f463d45e 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -257,6 +257,8 @@ const NO_WARNING_PACKAGES = [ 'plugins/scaffolder-common', 'plugins/search-backend-node', 'plugins/search-common', + 'plugins/techdocs', + 'plugins/techdocs-addons', 'plugins/techdocs-backend', 'plugins/techdocs-node', 'plugins/tech-insights', @@ -264,7 +266,6 @@ const NO_WARNING_PACKAGES = [ 'plugins/tech-insights-backend-module-jsonfc', 'plugins/tech-insights-common', 'plugins/tech-insights-node', - 'plugins/techdocs', 'plugins/todo', 'plugins/todo-backend', ];