From 8976bc0e94bfd6b4a59a28c104d5f957bdcf53a5 Mon Sep 17 00:00:00 2001 From: Joshua Jung Date: Fri, 30 Aug 2024 11:35:08 -0500 Subject: [PATCH 1/4] Adding some documentation on how to use the TechDocs extensions Signed-off-by: Joshua Jung --- docs/features/techdocs/extensions.md | 54 ++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 55 insertions(+) create mode 100644 docs/features/techdocs/extensions.md diff --git a/docs/features/techdocs/extensions.md b/docs/features/techdocs/extensions.md new file mode 100644 index 0000000000..c92939ad0b --- /dev/null +++ b/docs/features/techdocs/extensions.md @@ -0,0 +1,54 @@ +--- +id: extensions +title: Using TechDocs Extensions +sidebar_label: Using TechDocs Extensions +description: How to use the built-in TechDocs extension points +--- + +# TechDocs Backend Extensions + +The TechDocs backend plugin provides the following extension points: + +- `techdocsBuildsExtensionPoint` +- `techdocsGeneratorExtensionPoint` +- `techdocsPreparerExtensionPoint` +- `techdocsPublisherExtensionPoint` + +## Build Extensions + +### Set Log Transport + +By default, the TechDocs build phase does not log out much information while building out TechDocs. However, the +`techdocsBuildsExtensionPoint` can be used to setup a custom Winston transport for TechDocs build logs. + +Here is an example of logging to console: + +```typescript jsx title="packages/backend/src/extensions/techDocsExtension.ts" +import { techdocsBuildsExtensionPoint } from '@backstage/plugin-techdocs-backend'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +import { transports } from 'winston'; + +export const techDocsExtension = createBackendModule({ + pluginId: 'techdocs', + moduleId: 'extension', + register(env) { + env.registerInit({ + deps: { + build: techdocsBuildsExtensionPoint, + }, + async init({ build }) { + // You can obviously use any custom transport here... + build.setBuildLogTransport(new transports.Console()); + }, + }); + }, +}); +``` + +And then of course register this extension with the backend: + +```typescript jsx title="packages/backend/src/index.ts" +import {techDocsExtension} from "./extensions/techDocsExtension"; +... +backend.add(techDocsExtension()); +``` diff --git a/mkdocs.yml b/mkdocs.yml index b2d0a5489d..aa545111d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ nav: - Configuring CI/CD to generate and publish TechDocs sites: 'features/techdocs/configuring-ci-cd.md' - CLI: 'features/techdocs/cli.md' - HOW TO guides: 'features/techdocs/how-to-guides.md' + - Extensions: 'features/techdocs/extensions.md' - Troubleshooting: 'features/techdocs/troubleshooting.md' - FAQ: 'features/techdocs/FAQ.md' - Integrations: From 7b882b898f76cb7f869c3c9dd39d31b17b8bff74 Mon Sep 17 00:00:00 2001 From: Joshua Jung Date: Thu, 5 Sep 2024 11:50:30 -0500 Subject: [PATCH 2/4] Fixing issues addressed in PR comments Signed-off-by: Joshua Jung --- docs/features/techdocs/extensions.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/features/techdocs/extensions.md b/docs/features/techdocs/extensions.md index c92939ad0b..dc00bbe150 100644 --- a/docs/features/techdocs/extensions.md +++ b/docs/features/techdocs/extensions.md @@ -9,14 +9,22 @@ description: How to use the built-in TechDocs extension points The TechDocs backend plugin provides the following extension points: -- `techdocsBuildsExtensionPoint` -- `techdocsGeneratorExtensionPoint` - `techdocsPreparerExtensionPoint` + - Register a custom docs [PreparerBase extension](/docs/reference/plugin-techdocs-node.preparerbase/) + - Ideal for when you want a custom type of docs created for a specific entity type +- `techdocsBuildsExtensionPoint` + - Allows overriding the build phase Winston log transport (by default does not log to console) + - Allows overriding the [DocsBuildStrategy](/docs/reference/plugin-techdocs-node.docsbuildstrategy) - `techdocsPublisherExtensionPoint` + - Register a custom docs publisher +- `techdocsGeneratorExtensionPoint` + - Register a custom [TechdocsGenerator](/docs/reference/plugin-techdocs-node.techdocsgenerator/) -## Build Extensions +Extension points are exported from `@backstage/plugin-techdocs-backend`. -### Set Log Transport +## Examples + +### Log TechDocs Build phase details to console By default, the TechDocs build phase does not log out much information while building out TechDocs. However, the `techdocsBuildsExtensionPoint` can be used to setup a custom Winston transport for TechDocs build logs. @@ -30,7 +38,7 @@ import { transports } from 'winston'; export const techDocsExtension = createBackendModule({ pluginId: 'techdocs', - moduleId: 'extension', + moduleId: 'techdocs-build-log-transport-extension', register(env) { env.registerInit({ deps: { @@ -50,5 +58,5 @@ And then of course register this extension with the backend: ```typescript jsx title="packages/backend/src/index.ts" import {techDocsExtension} from "./extensions/techDocsExtension"; ... -backend.add(techDocsExtension()); +backend.add(techDocsExtension); ``` From b24938cd19c6cca51eaf1967b86d3149dbfa6a59 Mon Sep 17 00:00:00 2001 From: Joshua Jung Date: Thu, 5 Sep 2024 16:29:48 -0500 Subject: [PATCH 3/4] Attempt to fix the url references Signed-off-by: Joshua Jung --- docs/features/techdocs/extensions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/extensions.md b/docs/features/techdocs/extensions.md index dc00bbe150..2aff3c9725 100644 --- a/docs/features/techdocs/extensions.md +++ b/docs/features/techdocs/extensions.md @@ -10,15 +10,15 @@ description: How to use the built-in TechDocs extension points The TechDocs backend plugin provides the following extension points: - `techdocsPreparerExtensionPoint` - - Register a custom docs [PreparerBase extension](/docs/reference/plugin-techdocs-node.preparerbase/) + - Register a custom docs [PreparerBase extension](https://backstage.io/docs/reference/plugin-techdocs-node.preparerbase/) - Ideal for when you want a custom type of docs created for a specific entity type - `techdocsBuildsExtensionPoint` - Allows overriding the build phase Winston log transport (by default does not log to console) - - Allows overriding the [DocsBuildStrategy](/docs/reference/plugin-techdocs-node.docsbuildstrategy) + - Allows overriding the [DocsBuildStrategy](https://backstage.io/docs/reference/plugin-techdocs-node.docsbuildstrategy/) - `techdocsPublisherExtensionPoint` - Register a custom docs publisher - `techdocsGeneratorExtensionPoint` - - Register a custom [TechdocsGenerator](/docs/reference/plugin-techdocs-node.techdocsgenerator/) + - Register a custom [TechdocsGenerator](https://backstage.io/docs/reference/plugin-techdocs-node.techdocsgenerator/) Extension points are exported from `@backstage/plugin-techdocs-backend`. From 5bf256adbcdd263844e8e8b0a9a26048e9ce1ad9 Mon Sep 17 00:00:00 2001 From: Joshua Jung Date: Tue, 10 Sep 2024 15:18:31 -0500 Subject: [PATCH 4/4] Update per PR review Signed-off-by: Joshua Jung --- docs/features/techdocs/extensions.md | 2 +- microsite/sidebars.json | 561 +++++++++++++++++++++++++++ 2 files changed, 562 insertions(+), 1 deletion(-) create mode 100644 microsite/sidebars.json diff --git a/docs/features/techdocs/extensions.md b/docs/features/techdocs/extensions.md index 2aff3c9725..6c69d076a4 100644 --- a/docs/features/techdocs/extensions.md +++ b/docs/features/techdocs/extensions.md @@ -26,7 +26,7 @@ Extension points are exported from `@backstage/plugin-techdocs-backend`. ### Log TechDocs Build phase details to console -By default, the TechDocs build phase does not log out much information while building out TechDocs. However, the +By default, the TechDocs build phase logs to the UI, but does not log to the console. However, the `techdocsBuildsExtensionPoint` can be used to setup a custom Winston transport for TechDocs build logs. Here is an example of logging to console: diff --git a/microsite/sidebars.json b/microsite/sidebars.json new file mode 100644 index 0000000000..014456b1d9 --- /dev/null +++ b/microsite/sidebars.json @@ -0,0 +1,561 @@ +{ + "releases": { + "Release Notes": [ + "releases/v1.30.0", + "releases/v1.29.0", + "releases/v1.28.0", + "releases/v1.27.0", + "releases/v1.26.0", + "releases/v1.25.0", + "releases/v1.24.0", + "releases/v1.23.0", + "releases/v1.22.0", + "releases/v1.21.0", + "releases/v1.20.0", + "releases/v1.19.0", + "releases/v1.18.0", + "releases/v1.17.0", + "releases/v1.16.0", + "releases/v1.15.0", + "releases/v1.14.0", + "releases/v1.13.0", + "releases/v1.12.0", + "releases/v1.11.0", + "releases/v1.10.0", + "releases/v1.9.0", + "releases/v1.8.0", + "releases/v1.7.0", + "releases/v1.6.0", + "releases/v1.5.0", + "releases/v1.4.0", + "releases/v1.3.0", + "releases/v1.2.0", + "releases/v1.1.0", + "releases/v1.0.0" + ] + }, + "docs": { + "Overview": [ + "overview/what-is-backstage", + "overview/architecture-overview", + "overview/roadmap", + "overview/vision", + "overview/background", + "overview/adopting", + "overview/versioning-policy", + "overview/threat-model", + "overview/support", + "overview/logos" + ], + "Getting Started": [ + "getting-started/index", + { + "type": "category", + "label": "Configuring Backstage", + "items": [ + "getting-started/config/database", + "getting-started/config/authentication", + "getting-started/configure-app-with-plugins", + "getting-started/app-custom-theme", + "getting-started/homepage" + ] + }, + { + "type": "category", + "label": "Using Backstage", + "items": [ + "getting-started/logging-in", + "getting-started/register-a-component", + "getting-started/create-a-component" + ] + }, + "getting-started/keeping-backstage-updated", + "getting-started/concepts" + ], + "Core Features": [ + { + "type": "category", + "label": "Software Catalog", + "items": [ + "features/software-catalog/software-catalog-overview", + "features/software-catalog/life-of-an-entity", + "features/software-catalog/configuration", + "features/software-catalog/system-model", + "features/software-catalog/descriptor-format", + "features/software-catalog/references", + "features/software-catalog/well-known-annotations", + "features/software-catalog/well-known-relations", + "features/software-catalog/well-known-statuses", + "features/software-catalog/extending-the-model", + "features/software-catalog/external-integrations", + "features/software-catalog/catalog-customization", + "features/software-catalog/software-catalog-api", + "features/software-catalog/creating-the-catalog-graph" + ] + }, + { + "type": "category", + "label": "Kubernetes", + "items": [ + "features/kubernetes/overview", + "features/kubernetes/installation", + "features/kubernetes/configuration", + "features/kubernetes/authentication", + "features/kubernetes/authentication-strategies", + "features/kubernetes/troubleshooting", + "features/kubernetes/proxy" + ] + }, + { + "type": "category", + "label": "Software Templates", + "items": [ + "features/software-templates/software-templates-index", + "features/software-templates/configuration", + "features/software-templates/adding-templates", + "features/software-templates/writing-templates", + "features/software-templates/input-examples", + "features/software-templates/builtin-actions", + "features/software-templates/writing-custom-actions", + "features/software-templates/writing-tests-for-actions", + "features/software-templates/writing-custom-field-extensions", + "features/software-templates/writing-custom-step-layouts", + "features/software-templates/authorizing-scaffolder-template-details", + "features/software-templates/migrating-to-rjsf-v5", + "features/software-templates/migrating-from-v1beta2-to-v1beta3", + "features/software-templates/dry-run-testing" + ] + }, + { + "type": "category", + "label": "Backstage Search", + "items": [ + "features/search/search-overview", + "features/search/getting-started", + "features/search/concepts", + "features/search/architecture", + "features/search/search-engines", + "features/search/collators", + "features/search/how-to-guides" + ] + }, + { + "type": "category", + "label": "TechDocs", + "items": [ + "features/techdocs/techdocs-overview", + "features/techdocs/getting-started", + "features/techdocs/concepts", + "features/techdocs/addons", + "features/techdocs/architecture", + "features/techdocs/extensions", + "features/techdocs/creating-and-publishing", + "features/techdocs/configuration", + "features/techdocs/using-cloud-storage", + "features/techdocs/configuring-ci-cd", + "features/techdocs/cli", + "features/techdocs/how-to-guides", + "features/techdocs/troubleshooting", + "features/techdocs/faqs" + ] + } + ], + "Integrations": [ + "integrations/index", + { + "type": "category", + "label": "AWS S3", + "items": [ + "integrations/aws-s3/locations", + "integrations/aws-s3/discovery" + ] + }, + { + "type": "category", + "label": "Azure", + "items": [ + "integrations/azure/locations", + "integrations/azure/discovery", + "integrations/azure/org" + ] + }, + { + "type": "category", + "label": "Bitbucket Cloud", + "items": [ + "integrations/bitbucketCloud/locations", + "integrations/bitbucketCloud/discovery" + ] + }, + { + "type": "category", + "label": "Bitbucket Server", + "items": [ + "integrations/bitbucketServer/locations", + "integrations/bitbucketServer/discovery" + ] + }, + { + "type": "category", + "label": "Datadog", + "items": ["integrations/datadog-rum/installation"] + }, + { + "type": "category", + "label": "Gerrit", + "items": [ + "integrations/gerrit/locations", + "integrations/gerrit/discovery" + ] + }, + { + "type": "category", + "label": "GitHub", + "items": [ + "integrations/github/locations", + "integrations/github/discovery", + "integrations/github/org", + "integrations/github/github-apps" + ] + }, + { + "type": "category", + "label": "GitLab", + "items": [ + "integrations/gitlab/locations", + "integrations/gitlab/discovery", + "integrations/gitlab/org" + ] + }, + { + "type": "category", + "label": "Gitea", + "items": ["integrations/gitea/locations"] + }, + { + "type": "category", + "label": "Harness", + "items": ["integrations/harness/locations"] + }, + { + "type": "category", + "label": "Google GCS", + "items": ["integrations/google-cloud-storage/locations"] + }, + { + "type": "category", + "label": "LDAP", + "items": ["integrations/ldap/org"] + } + ], + "Plugins": [ + "plugins/index", + "plugins/existing-plugins", + "plugins/create-a-plugin", + "plugins/plugin-development", + "plugins/structure-of-a-plugin", + "plugins/integrating-plugin-into-software-catalog", + "plugins/integrating-search-into-plugins", + "plugins/composability", + "plugins/internationalization", + "plugins/analytics", + "plugins/feature-flags", + { + "type": "category", + "label": "OpenAPI", + "items": [ + "openapi/01-getting-started", + "openapi/generate-client", + "openapi/test-case-validation" + ] + }, + { + "type": "category", + "label": "Backends and APIs", + "items": [ + "plugins/proxying", + "plugins/backend-plugin", + "plugins/call-existing-api" + ] + }, + { + "type": "category", + "label": "Testing", + "items": ["plugins/testing"] + }, + { + "type": "category", + "label": "Publishing", + "items": [ + "plugins/publish-private", + "plugins/add-to-directory", + "plugins/observability" + ] + } + ], + "Configuration": [ + "conf/index", + "conf/reading", + "conf/writing", + "conf/defining" + ], + "Notifications": ["notifications/index"], + "Auth and identity": [ + "auth/index", + { + "type": "category", + "label": "Included providers", + "items": [ + "auth/auth0/provider", + "auth/atlassian/provider", + "auth/aws-alb/provider", + "auth/microsoft/provider", + "auth/microsoft/easy-auth", + "auth/bitbucket/provider", + "auth/bitbucketServer/provider", + "auth/cloudflare/provider", + "auth/github/provider", + "auth/gitlab/provider", + "auth/google/provider", + "auth/google/gcp-iap-auth", + "auth/guest/provider", + "auth/okta/provider", + "auth/oauth2-proxy/provider", + "auth/onelogin/provider", + "auth/vmware-cloud/provider" + ] + }, + "auth/identity-resolver", + "auth/oauth", + "auth/oidc", + "auth/add-auth-provider", + "auth/service-to-service-auth", + "auth/autologout", + "auth/troubleshooting" + ], + "Permissions": [ + "permissions/overview", + "permissions/concepts", + "permissions/getting-started", + "permissions/writing-a-policy", + "permissions/frontend-integration", + "permissions/custom-rules", + { + "type": "category", + "label": "Tutorial: using Permissions in your plugin", + "items": [ + "permissions/plugin-authors/01-setup", + "permissions/plugin-authors/02-adding-a-basic-permission-check", + "permissions/plugin-authors/03-adding-a-resource-permission-check", + "permissions/plugin-authors/04-authorizing-access-to-paginated-data", + "permissions/plugin-authors/05-frontend-authorization" + ] + } + ], + "Tooling": [ + { + "type": "category", + "label": "Backstage CLI", + "items": [ + "tooling/cli/overview", + "tooling/cli/build-system", + "tooling/cli/commands" + ] + }, + { + "type": "category", + "label": "Local Development", + "items": [ + "tooling/local-dev/linking-local-packages", + "tooling/local-dev/debugging", + "tooling/local-dev/profiling" + ] + }, + "tooling/package-metadata" + ], + "Deployment": [ + "deployment/index", + "deployment/scaling", + "deployment/docker", + "deployment/k8s", + "deployment/heroku", + "deployment/koyeb", + "deployment/flightcontrol", + { + "type": "category", + "label": "Using Backstage Deploy (alpha)", + "items": ["deployment/backstage-deploy/aws-lightsail"] + } + ], + "New Backend System": [ + "backend-system/index", + { + "type": "category", + "label": "Architecture", + "items": [ + "backend-system/architecture/index", + "backend-system/architecture/services", + "backend-system/architecture/plugins", + "backend-system/architecture/extension-points", + "backend-system/architecture/modules", + "backend-system/architecture/feature-loaders", + "backend-system/architecture/naming-patterns" + ] + }, + { + "type": "category", + "label": "Building Backends", + "items": [ + "backend-system/building-backends/index", + "backend-system/building-backends/migrating" + ] + }, + { + "type": "category", + "label": "Building Plugins & Modules", + "items": [ + "backend-system/building-plugins-and-modules/index", + "backend-system/building-plugins-and-modules/testing", + "backend-system/building-plugins-and-modules/migrating" + ] + }, + { + "type": "category", + "label": "Core Services", + "items": [ + "backend-system/core-services/index", + "backend-system/core-services/auth", + "backend-system/core-services/cache", + "backend-system/core-services/database", + "backend-system/core-services/discovery", + "backend-system/core-services/http-auth", + "backend-system/core-services/http-router", + "backend-system/core-services/identity", + "backend-system/core-services/lifecycle", + "backend-system/core-services/logger", + "backend-system/core-services/permissions", + "backend-system/core-services/plugin-metadata", + "backend-system/core-services/root-config", + "backend-system/core-services/root-health", + "backend-system/core-services/root-http-router", + "backend-system/core-services/root-lifecycle", + "backend-system/core-services/root-logger", + "backend-system/core-services/scheduler", + "backend-system/core-services/token-manager", + "backend-system/core-services/url-reader", + "backend-system/core-services/user-info" + ] + } + ], + "New Frontend System": [ + "frontend-system/index", + { + "type": "category", + "label": "Architecture", + "items": [ + "frontend-system/architecture/index", + "frontend-system/architecture/app", + "frontend-system/architecture/plugins", + "frontend-system/architecture/extensions", + "frontend-system/architecture/extension-blueprints", + "frontend-system/architecture/extension-overrides", + "frontend-system/architecture/references", + "frontend-system/architecture/utility-apis", + "frontend-system/architecture/routes", + "frontend-system/architecture/naming-patterns", + "frontend-system/architecture/migrations" + ] + }, + { + "type": "category", + "label": "Building Plugins", + "items": [ + "frontend-system/building-plugins/index", + "frontend-system/building-plugins/testing", + "frontend-system/building-plugins/common-extension-blueprints", + "frontend-system/building-plugins/built-in-data-refs", + "frontend-system/building-plugins/migrating" + ] + }, + { + "type": "category", + "label": "Building Apps", + "items": [ + "frontend-system/building-apps/index", + "frontend-system/building-apps/configuring-extensions", + "frontend-system/building-apps/built-in-extensions", + "frontend-system/building-apps/plugin-conversion", + "frontend-system/building-apps/migrating" + ] + }, + { + "type": "category", + "label": "Utility APIs", + "items": [ + "frontend-system/utility-apis/index", + "frontend-system/utility-apis/creating", + "frontend-system/utility-apis/consuming", + "frontend-system/utility-apis/configuring" + ] + } + ], + "Designing for Backstage": [ + "dls/design", + "dls/component-design-guidelines", + "dls/contributing-to-storybook", + "dls/figma" + ], + "API Reference": [ + { + "type": "category", + "label": "Guides", + "items": ["api/utility-apis"] + }, + { + "type": "category", + "label": "API Reference", + "items": ["reference/index"] + }, + "api/deprecations" + ], + "Tutorials": [ + "tutorials/quickstart-app-plugin", + "tutorials/react-router-stable-migration", + "tutorials/react18-migration", + "tutorials/package-role-migration", + "tutorials/migrating-away-from-core", + "tutorials/configuring-plugin-databases", + "tutorials/switching-sqlite-postgres", + "tutorials/using-backstage-proxy-within-plugin", + "tutorials/yarn-migration", + "tutorials/migrate-to-mui5", + "tutorials/auth-service-migration", + "tutorials/enable-public-entry", + "tutorials/setup-opentelemetry" + ], + "Architecture Decision Records (ADRs)": [ + "architecture-decisions/adrs-overview", + "architecture-decisions/adrs-adr001", + "architecture-decisions/adrs-adr002", + "architecture-decisions/adrs-adr003", + "architecture-decisions/adrs-adr004", + "architecture-decisions/adrs-adr005", + "architecture-decisions/adrs-adr006", + "architecture-decisions/adrs-adr007", + "architecture-decisions/adrs-adr008", + "architecture-decisions/adrs-adr009", + "architecture-decisions/adrs-adr010", + "architecture-decisions/adrs-adr011", + "architecture-decisions/adrs-adr012", + "architecture-decisions/adrs-adr013" + ], + "FAQ": ["faq/index", "faq/product", "faq/technical"], + "Accessibility": ["accessibility/index"], + "Contribute": [ + "contribute/index", + "contribute/getting-involved", + "contribute/project-structure" + ], + "References": ["references/glossary"] + } +}