paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 27 Packages Projects Releases Wiki Activity

Merge branch 'master' into nikolarAutodesk/makeTechDocsCustomizable

Browse Source 
Signed-off-by: Reyna Nikolayev <146387693+nikolarAutodesk@users.noreply.github.com>
This commit is contained in:
Reyna Nikolayev
2024-12-10 16:40:53 -08:00
committed by GitHub
parent 0d7097b705 d75a2699f0
commit 845b0f17f5
1425 changed files with 48552 additions and 8946 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-templates/experimental.md
+87
View File
@@ -0,0 +1,87 @@
---
id: experimental
title: Experimental Features
# prettier-ignore
description: Information on Experimental Features that are currently available in the Scaffolder
---
## Introduction
This section contains information and guides on the experimental features that are currently available in the Scaffolder. Be advised that these features are still in development and may not be fully stable or complete, and are subject to change at any time.
Please leave feedback on these features in the [Backstage Discord](https://discord.com/invite/MUpMjP2) or by [creating an issue](https://github.com/backstage/backstage/issues/new/choose) on the Backstage GitHub repository.
## Retries and Recovery
### TODO
## Form Decorators
Form decorators provide the ability to run arbitrary code before the form is submitted along with secrets to the `scaffolder-backend` plugin. They are provided to the `app` using a Utility API.
#### Installation
To install the Form Decorators, add the following to your `packages/app/src/apis.ts`:
```ts
createApiFactory({
api: formDecoratorsApiRef,
deps: {},
factory: () =>
DefaultScaffolderFormDecoratorsApi.create({
decorators: [
// add decorators here
],
}),
}),
```
And then you'll also need to define which decorators run in each template using the `EXPERIMENTAL_formDecorators` key in the template's `spec`:
```yaml
kind: Template
metadata:
name: my-template
spec:
EXPERIMENTAL_formDecorators:
- id: my-decorator
input:
test: something funky
parameters: ...
steps: ...
```
#### Creating a Decorator
You can create a decorator using the simple helper method `createScaffolderFormDecorator`:
```ts
export const mockDecorator = createScaffolderFormDecorator({
// give the decorator a name
id: 'mock-decorator',
// define the schema for the input that can be proided in `template.yaml`
schema: {
input: {
test: z => z.string(),
},
},
deps: {
// define dependencies here
githubApi: githubAuthApiRef,
},
decorator: async (
// Context has all the things needed to write simple decorators
{ setSecrets, setFormState, input: { test } },
// Depepdencies injected here
{ githubApi },
) => {
// mutate the form state
setFormState(state => ({ ...state, test, mock: 'MOCK' }));
// mutate the form secrets
setSecrets(state => ({ ...state, GITHUB_TOKEN: 'MOCK_TOKEN' }));
},
});
```
docs/features/software-templates/input-examples.md
+65
View File
@@ -198,6 +198,23 @@ parameters:
ui:widget: checkboxes
```
## Markdown text blocks
```yaml
parameters:
- title: Fill in some steps
properties:
markdown:
type: 'null' # Needs to be quoted
description: |
## Markdown Text Block
Standard markdown formatting is supported including *italics*, **bold** and [links](https://example.com)
* bullet 1
* bullet 2
```
## Use parameters as condition in steps
Conditions use Javascript equality operators.
@@ -250,6 +267,54 @@ parameters:
- lastName
```
### Multiple conditional fields with custom ordering
```yaml
parameters:
- title: Fill in some steps
ui:order:
- includeName
- lastName
- includeAddress
- address
properties:
includeName:
title: Include Name?
type: boolean
default: true
includeAddress:
title: Include Address?
type: boolean
default: true
dependencies:
includeName:
allOf:
- if:
properties:
includeName:
const: true
then:
properties:
lastName:
title: Name
type: string
required:
- lastName
includeAddress:
allOf:
- if:
properties:
includeAddress:
const: true
then:
properties:
address:
title: Address
type: string
required:
- address
```
## Conditionally set parameters
The `if` keyword within the parameter uses [nunjucks templating](https://mozilla.github.io/nunjucks/templating.html#if). The `not` keyword is unavailable; instead, use javascript equality.
docs/features/software-templates/writing-custom-actions.md
+33
View File
@@ -141,6 +141,39 @@ Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if
> We're aware that there are some exceptions to this, but try to follow as close as possible. We'll be working on migrating these in the repository over time too.
### Adding a TemplateExample
A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It serves as a blueprint for users to understand how to use a specific action and its fields as well as to ensure consistency and standardization across different custom actions.
#### Define a TemplateExample and add to your Custom Action
```ts title="With JSON Schema"
import { TemplateExample } from '@backstage/plugin-scaffolder-node';
import yaml from 'yaml';
export const examples: TemplateExample[] = [
{
description: 'Template Example for Creating an Acme file',
example: yaml.stringify({
steps: [
{
action: 'acme:file:create',
name: 'Create an Acme file.',
input: {
contents: 'file contents...',
filename: 'ACME.properties',
},
},
],
}),
},
];
```
Add the example to the `createTemplateAction` under the object property `examples`:
`return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...};`
### The context object
When the action `handler` is called, we provide you a `context` as the only
docs/features/techdocs/addons.md
+1 -1
View File
@@ -186,7 +186,7 @@ import { useShadowRootElements } from '@backstage/plugin-techdocs-react';
// difference is that you'd set `location` to `TechDocsAddonLocations.Content`.
export const MakeAllImagesCatGifsAddon = () => {
// This hook can be used to get references to specific elements. If you need
// access to the whole shadow DOM, use the the underlying useShadowRoot()
// access to the whole shadow DOM, use the underlying useShadowRoot()
// hook instead.
const images = useShadowRootElements<HTMLImageElement>(['img']);
docs/features/techdocs/getting-started.md
+3 -1
View File
@@ -297,7 +297,9 @@ You can do so by including the following lines right above `USER node` of your
`Dockerfile`:
```Dockerfile
RUN apt-get update && apt-get install -y python3 python3-pip python3-venv
RUN apt-get update && \
apt-get install -y python3 python3-pip python3-venv && \
rm -rf /var/lib/apt/lists/*
ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
docs/features/techdocs/how-to-guides.md
+16 -5
View File
@@ -639,7 +639,7 @@ Note: To refer external diagram files, we need to include the diagrams directory
## How to add Mermaid support in TechDocs
There are two options for adding Mermaid support in TechDocs: using [Kroki](https://kroki.io) or by using [markdown-inline-mermaid](https://github.com/johanneswuerbach/markdown-inline-mermaid). We currently use `markdown-inline-mermaid` for the [Mermaid example on the Demo site](https://demo.backstage.io/docs/default/component/backstage-demo/examples/mermaid/).
There are a few options for adding Mermaid support in TechDocs: using [Kroki](https://kroki.io) or [markdown-inline-mermaid](https://github.com/johanneswuerbach/markdown-inline-mermaid) to generate the diagrams at build time, or the [`backstage-plugin-techdocs-addon-mermaid`](https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid) plugin to generate the diagram in the browser. We currently use `backstage-plugin-techdocs-addon-mermaid` plugin for the [Mermaid example on the Demo site](https://demo.backstage.io/docs/default/component/backstage-demo/examples/mermaid/).
### Using Kroki
@@ -745,16 +745,23 @@ Done! Now you have a support of the following diagrams along with mermaid:
To use `markdown-inline-mermaid` to generate your Mermaid diagrams in TechDocs you'll need to do the following:
1. In your Dockerfile you will need to make sure you install `markdown-inline-mermaid` like this: `RUN pip3 install mkdocs-techdocs-core markdown-inline-mermaid`
2. You will also need to install the `@mermaid-js/mermaid-cli`, to do that add this: `RUN yarn global add @mermaid-js/mermaid-cli`
3. Now in your `mkdocs.yml` file you will need to add the following section (this is at the root level like `plugins` which you should already have):
1. In your Dockerfile you will need to make sure you install `markdown-inline-mermaid` and its dependencies, you will also need to install the `@mermaid-js/mermaid-cli`:
```dockerfile title="Dockerfile"
RUN apt-get install -y chromium
RUN pip3 install mkdocs-techdocs-core markdown-inline-mermaid
RUN npm install -g @mermaid-js/mermaid-cli
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
```
2. Now in your `mkdocs.yml` file you will need to add the following section (this is at the root level like `plugins` which you should already have):
```yaml title="mkdocs.yml"
markdown_extensions:
- markdown_inline_mermaid
```
4. With this in place you can now add Mermaid diagrams in your Markdown files like this:
3. With this in place you can now add Mermaid diagrams in your Markdown files like this:
````md
```mermaid
@@ -765,6 +772,10 @@ To use `markdown-inline-mermaid` to generate your Mermaid diagrams in TechDocs y
```
````
### Using the `backstage-plugin-techdocs-addon-mermaid` plugin
Please follow the [Getting Started](https://github.com/johanneswuerbach/backstage-plugin-techdocs-addon-mermaid?tab=readme-ov-file#getting-started) instructions in the plugin's README.
## How to implement a hybrid build strategy
One limitation of the [Recommended deployment](./architecture.md#recommended-deployment) is that