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

feat(techdocs) update documentation and add change set

Browse Source 
Signed-off-by: jrwpatterson <jrwpatterson@gmail.com>
This commit is contained in:
jrwpatterson
2023-08-09 08:22:13 +10:00
parent b88968fada
commit e44f45ac45
2 changed files with 35 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/modern-trees-add.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/plugin-techdocs': minor
'@backstage/plugin-catalog': minor
---
This change allows a new annotation of `backstage.io/techdocs-external-ref` this ref allows you to reference another entity for its TechDocs. This allows you have a single TechDoc for all items in a system, for example you might have a frontend and a backend in the same repo. This would allow you to have TechDocs build under a `System` entity while referencing the system e.g.: `backstage.io/techdocs-external-ref: system:default/example` that will show the systems docs in both the TechDocs button and the TechDocs tab without needing to do duplicate builds and filling the TechDocs page with garbage.
docs/features/techdocs/how-to-guides.md
+29
View File
@@ -678,3 +678,32 @@ entity. If the value of this annotation is `'local'`, the TechDocs backend will
and publish the documentation for them. If the value of the `company.com/techdocs-builder`
annotation is anything other than `'local'`, the user is responsible for publishing
documentation to the appropriate location in the TechDocs external storage.
## Reference another components TechDocs
In systems where you might have multiple entities for example a System with a Website and an API, when served from a Monorepo you might want to keep the TechDocs in one location in the repository.
In this case you can add the `backstage.io/techdocs-external-ref` annotation and point to the owners `entityRef` and use its TechDocs. This allows the Subcomponents to read the parents docs, filling the TechDocs link on the `AboutCard` element and the Techdocs tab
```yaml
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
name: example
namespace: default
title: Example
description: This is the parent entity
annotations:
backstage.io/techdocs-ref: dir:.
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: example-platfrom
title: Example Application Platform
namespace: default
description: This is the child entity
annotations:
backstage.io/techdocs-external-ref: system:default/example
```