Merge branch 'master' of github.com:backstage/backstage into adamdmharvey/fix-docs
Signed-off-by: Adam Harvey <adaharve@cisco.com>
This commit is contained in:
Adam Harvey
+8
-6
@@ -69,6 +69,14 @@ of Material-UI, you are able to adapt the interface to your brand guidelines.
|
||||
|
||||
## Technical FAQ
|
||||
|
||||
### What technology does Backstage use?
|
||||
|
||||
Backstage is a large scale [TypeScript](https://www.typescriptlang.org/)
|
||||
application whose frontend parts use [React](https://react.dev/) and
|
||||
[Material-UI](https://mui.com/), while the backend parts use
|
||||
[Node.js](https://nodejs.org/) and the [Express](https://expressjs.com/)
|
||||
framework.
|
||||
|
||||
### Why Material-UI?
|
||||
|
||||
The short answer is that's what we've been using in Backstage internally.
|
||||
@@ -83,12 +91,6 @@ core focus of Backstage is to make plugin developers productive with as few
|
||||
hurdles as possible. Material-UI lets plugin makers get going easily with both
|
||||
well-known tech and a large flora of components.
|
||||
|
||||
### What technology does Backstage use?
|
||||
|
||||
The codebase is a large-scale React application that uses TypeScript. For
|
||||
[Phase 2](https://github.com/backstage/backstage#project-roadmap), we plan to
|
||||
use Node.js and GraphQL.
|
||||
|
||||
### What is the end-to-end user flow? The happy path story.
|
||||
|
||||
There are three main user profiles for Backstage: the integrator, the
|
||||
|
||||
@@ -23,8 +23,7 @@ compound reference structure.
|
||||
|
||||
## String References
|
||||
|
||||
This is the most common alternative, that should be used in almost all
|
||||
circumstances.
|
||||
This is the most common alternative, that is used in almost all circumstances.
|
||||
|
||||
The string is on the form `[<kind>:][<namespace>/]<name>`, that is, it is
|
||||
composed of between one and three parts in this specific order, without any
|
||||
@@ -75,30 +74,16 @@ essentially expand to `api:external-systems/petstore`,
|
||||
`api:internal/streetlights`, and `api:external-systems/hello-world`. We expect
|
||||
there to exist three API kind entities in the catalog matching those references.
|
||||
|
||||
Note that the remarks above in regards to shortening (leaving out kind and/or
|
||||
namespace) _only_ apply for the entity input YAML data. In protocols, storage
|
||||
systems, or when referring to entities externally, the entity ref always
|
||||
consists of all three parts.
|
||||
|
||||
## Compound References
|
||||
|
||||
This is a more verbose version of a reference, where each part of the
|
||||
kind-namespace-name triplet is expressed as a field in a structure. This format
|
||||
can be used where necessary, such as if either of the three elements contains
|
||||
colons or forward slashes. Avoid using it where possible, since it is harder to
|
||||
read and write for humans.
|
||||
|
||||
```yaml
|
||||
# Example:
|
||||
apiVersion: backstage.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: petstore
|
||||
description: Petstore
|
||||
spec:
|
||||
type: service
|
||||
lifecycle: experimental
|
||||
owner:
|
||||
kind: Group
|
||||
name: aegis-imports/pet-managers
|
||||
```
|
||||
|
||||
In this example, the `spec.owner` has been broken apart since the name was
|
||||
complex. The kind happened to be written with an uppercase letter G, which also
|
||||
works. The namespace was left out just like in the string version above, which
|
||||
is handled identically.
|
||||
kind-namespace-name triplet is expressed as a field in an object. You may see
|
||||
this structure used in Backstage code, but it should normally not be used in any
|
||||
form of protocol or between plugins and/or external systems. For those cases,
|
||||
instead prefer to use the string form which has clearer semantics and can be
|
||||
transported more easily since it's just a string.
|
||||
|
||||
@@ -491,7 +491,7 @@ plugins:
|
||||
|
||||
The `docs/index.md` can for example have the following content:
|
||||
|
||||
```
|
||||
```markdown
|
||||
# ${{ values.component_id }}
|
||||
|
||||
${{ values.description }}
|
||||
@@ -509,8 +509,8 @@ Done! You now have support for TechDocs in your own software template!
|
||||
|
||||
## How to enable iframes in TechDocs
|
||||
|
||||
TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to sanitize
|
||||
HTML and prevent XSS attacks.
|
||||
TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to
|
||||
sanitize HTML and prevent XSS attacks.
|
||||
|
||||
It's possible to allow some iframes based on a list of allowed hosts. To do
|
||||
this, add the allowed hosts in the `techdocs.sanitizer.allowedIframeHosts`
|
||||
@@ -530,20 +530,20 @@ This way, all iframes where the host in the src attribute is in the
|
||||
|
||||
## How to add Mermaid support in TechDocs
|
||||
|
||||
To add `Mermaid` support in Techdocs, you can use [`kroki`](https://kroki.io)
|
||||
To add `Mermaid` support in TechDocs, you can use [`kroki`](https://kroki.io)
|
||||
that creates diagrams from Textual descriptions. It is a single rendering
|
||||
gateway for all popular diagrams-as-a-code tools. It supports an enormous number
|
||||
of diagram types.
|
||||
|
||||
1. **Create and Publish docker image:** Create the docker image from the
|
||||
following Dockerfile and publish it to DockerHub.
|
||||
1. **Create and Publish Docker image:** Create the Docker image from the
|
||||
following `Dockerfile` and publish it to DockerHub.
|
||||
|
||||
```docker
|
||||
FROM python:3.8-alpine
|
||||
FROM python:3.10-alpine
|
||||
|
||||
RUN apk update && apk --no-cache add gcc musl-dev openjdk11-jdk curl graphviz ttf-dejavu fontconfig
|
||||
|
||||
RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.1.7
|
||||
RUN pip install --upgrade pip && pip install mkdocs-techdocs-core==1.2.0
|
||||
|
||||
RUN pip install mkdocs-kroki-plugin
|
||||
|
||||
@@ -551,7 +551,7 @@ ENTRYPOINT [ "mkdocs" ]
|
||||
```
|
||||
|
||||
Create a repository in your DockerHub and run the below command in the same
|
||||
folder where your Dockerfile is present:
|
||||
folder where your `Dockerfile` is present:
|
||||
|
||||
```shell
|
||||
docker build . -t dockerHub_Username/repositoryName:tagName
|
||||
@@ -559,7 +559,7 @@ docker build . -t dockerHub_Username/repositoryName:tagName
|
||||
|
||||
Once the docker image is ready, push it to DockerHub.
|
||||
|
||||
2. **Update app-config.yaml:** So that when your app generates techdocs, it will
|
||||
2. **Update app-config.yaml:** So that when your app generates TechDocs, it will
|
||||
pull your docker image from DockerHub.
|
||||
|
||||
```python
|
||||
@@ -573,7 +573,7 @@ techdocs:
|
||||
type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
|
||||
```
|
||||
|
||||
3. **Add the `kroki` plugin in mkdocs.yml:**
|
||||
3. **Add the `kroki` plugin in `mkdocs.yml`:**
|
||||
|
||||
```yml
|
||||
plugins:
|
||||
@@ -588,7 +588,7 @@ plugins:
|
||||
> instead. Check out [mkdocs-kroki-plugin config](https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin#config)
|
||||
> for more plugin configuration details.
|
||||
|
||||
4. **Add mermaid code into techdocs:**
|
||||
4. **Add mermaid code into TechDocs:**
|
||||
|
||||
````md
|
||||
```kroki-mermaid
|
||||
|
||||
@@ -5,11 +5,24 @@ sidebar_label: Troubleshooting
|
||||
description: Troubleshooting for TechDocs
|
||||
---
|
||||
|
||||
## Failure to clone
|
||||
## Documentation not found when generating
|
||||
|
||||
TechDocs will fail to clone your docs if you have a git config which overrides
|
||||
the `https` protocol with `ssh` or something else. Make sure to remove your git
|
||||
config locally when you try TechDocs.
|
||||
This may happen if you have TechDocs set up using the "out-of-the-box"
|
||||
configuration, wherein documentation is built dynamically by the TechDocs
|
||||
backend, and your TechDocs files are being pulled from a git-based source
|
||||
control management system (e.g. GitHub, BitBucket, etc).
|
||||
|
||||
If you experience this, check that TechDocs-related files (e.g. markdown,
|
||||
assets, or the `mkdocs.yml` file) are not matched by an `export-ignore`
|
||||
attribute in a `.gitattributes` file in the relevant repository.
|
||||
|
||||
TechDocs' backend is not able to see such files, and therefore may generate
|
||||
partial (or no) TechDocs as a result.
|
||||
|
||||
You'll need to reconsider how you distribute tar archives based on your source
|
||||
code (and how you prevent internal documentation from being included in those
|
||||
archives). Alternatively, you could consider switching to the "recommended"
|
||||
TechDocs architecture (documentation generated and published in CI/CD).
|
||||
|
||||
## MkDocs Build Errors
|
||||
|
||||
|
||||
@@ -40,10 +40,10 @@ Inside your `packages/app` directory, create a new file where our new homepage c
|
||||
```tsx
|
||||
import React from 'react';
|
||||
|
||||
export const HomePage = () => {
|
||||
export const homePage = (
|
||||
/* We will shortly compose a pretty homepage here. */
|
||||
return <h1>Welcome to Backstage!</h1>;
|
||||
};
|
||||
<h1>Welcome to Backstage!</h1>
|
||||
);
|
||||
```
|
||||
|
||||
#### 3. Update router for the root `/` route
|
||||
@@ -161,13 +161,11 @@ import React from 'react';
|
||||
import Grid from '@material-ui/core/Grid';
|
||||
import { HomePageCompanyLogo } from '@backstage/plugin-home';
|
||||
|
||||
export const HomePage = () => {
|
||||
return (
|
||||
<Grid container spacing={3}>
|
||||
<Grid item xs={12} md={4}>
|
||||
<HomePageCompanyLogo />
|
||||
</Grid>
|
||||
export const homePage = (
|
||||
<Grid container spacing={3}>
|
||||
<Grid item xs={12} md={4}>
|
||||
<HomePageCompanyLogo />
|
||||
</Grid>
|
||||
);
|
||||
};
|
||||
</Grid>
|
||||
);
|
||||
```
|
||||
|
||||
@@ -13,6 +13,30 @@ or registered with the
|
||||
[catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import)
|
||||
plugin.
|
||||
|
||||
Using a service principal:
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
azure:
|
||||
- host: dev.azure.com
|
||||
credential:
|
||||
clientId: ${CLIENT_ID}
|
||||
clientSecret: ${CLIENT_SECRET}
|
||||
tenantId: ${TENANT_ID}
|
||||
```
|
||||
|
||||
Using a managed identity:
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
azure:
|
||||
- host: dev.azure.com
|
||||
credential:
|
||||
clientId: ${CLIENT_ID}
|
||||
```
|
||||
|
||||
Using a personal access token (PAT):
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
azure:
|
||||
@@ -22,11 +46,19 @@ integrations:
|
||||
|
||||
> Note: An Azure DevOps provider is added automatically at startup for
|
||||
> convenience, so you only need to list it if you want to supply a
|
||||
> [token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate).
|
||||
> [token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
|
||||
> a [service principal](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity),
|
||||
> or a [managed identity](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)
|
||||
|
||||
The configuration is a structure with two elements:
|
||||
The configuration is a structure with these elements:
|
||||
|
||||
- `host`: The DevOps host; only `dev.azure.com` is supported.
|
||||
- `token` (optional): A personal access token as expected by Azure DevOps.
|
||||
- `credential`: (optional): A service principal or managed identity
|
||||
|
||||
> Note: The token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
|
||||
> Note:
|
||||
>
|
||||
> - `token` and `credential` are mutually exclusive.
|
||||
> - You cannot use a service principal or managed identity for Azure DevOps Server (on-premises) organizations
|
||||
> - You can only use a service principal or managed identity for Azure AD backed Azure DevOps organizations
|
||||
> - The token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
|
||||
|
||||
@@ -136,3 +136,5 @@ integration:
|
||||
- `Issues`: `Read & write`
|
||||
- `Workflows`: `Read & write` (if templates include GitHub workflows)
|
||||
- `Commit statuses`: `Read-only`
|
||||
- `Variables`: `Read & write` (if templates include GitHub Action Repository Variables)
|
||||
- `Secrets`: `Read & write` (if templates include GitHub Action Repository Secrets)
|
||||
|
||||
@@ -261,8 +261,8 @@ returned identity.
|
||||
async (user, ctx): Promise<UserEntity | undefined> => {
|
||||
const entity = await defaultUserTransformer(user, ctx);
|
||||
|
||||
if (entity && user.organizationVerifiedDomainEmails) {
|
||||
entity.spec.profile!.email = user.organizationVerifiedDomainEmails[0] || '';
|
||||
if (entity && user.organizationVerifiedDomainEmails?.length) {
|
||||
entity.spec.profile!.email = user.organizationVerifiedDomainEmails[0];
|
||||
}
|
||||
|
||||
return entity;
|
||||
|
||||
@@ -109,3 +109,5 @@ export default async function createPlugin(
|
||||
```
|
||||
|
||||
If you don't want create location object if file with component definition do not exists in project, you can set the `skipReposWithoutExactFileMatch` option. That can reduce count of request to gitlab with 404 status code.
|
||||
|
||||
If you don't want to create location object if the project is a fork, you can set the `skipForkedRepos` option.
|
||||
|
||||
@@ -106,6 +106,16 @@ directly be used with a URL. Some example usages -
|
||||
Catalog using the `search` method to find files for a location URL containing
|
||||
a glob pattern.
|
||||
|
||||
Note that URL Readers which target git-based version control systems may, under
|
||||
the hood, leverage the ability to create tar archives based on a specific git
|
||||
commit-ish. A consequence of this is that files and directories configured with
|
||||
[the `export-ignore` attribute](https://git-scm.com/docs/gitattributes#_creating_an_archive)
|
||||
via `.gitattributes` will not be visible to the URL reader when using the
|
||||
`readTree` or `search` methods.
|
||||
|
||||
Be aware of this limitation and ensure that end-users of your plugin are also
|
||||
aware via, for example, documentation.
|
||||
|
||||
## Writing a new URL Reader
|
||||
|
||||
If the available URL Readers are not sufficient for your use case and you want
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user