blam
f60b02bec4
* 'master' of github.com:backstage/backstage: (23 commits) cli: fix windows tests Introduce slight bias towards positive trend in cost insights mock data core-api: rename BackstageRoutes to FlatRoutes Update plugins/catalog/src/hooks/useEntity.ts Fix parameter name in docstring for duration#inclusiveStartDateOf Adjust test Add changeset fix: token expiration in s, not ms Create loud-days-breathe.md Create polite-glasses-occur.md dev-utils: add a small label with the entity name to EntityGridItems dev-utils: add EntityGridItem for easily displaying various entity cards dev-utils: use dev index module as root for hot reloading dev-utils: add .registerPage for use with extensions catalog: rename EntityProvider to EntityLoaderProvider, and add new EntityProvider reduce close timeout to 100 ms changeset: add changeset for core-api RouteRef deprecations core-api: use typescript workaround for using private constructor instead of a runtime one core-api: deprecate RouteRef path and remove deprecated createSubRoute delay window close by 200 ms ...
@backstage/techdocs-common
Common functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli
This package is used by techdocs-backend to serve docs from different types of publishers (Google GCS, Local, etc.).
It is also used to build docs and publish them to storage, by both techdocs-backend and techdocs-cli.
Usage
Create a preparer instance from the preparers available at which takes an Entity instance. Run the docs generator on the prepared directory. Publish the generated directory files to a storage of your choice.
Example:
async () => {
const preparedDir = await preparer.prepare(entity);
const parsedLocationAnnotation = getLocationForEntity(entity);
const { resultDir } = await generator.run({
directory: preparedDir,
dockerClient: dockerClient,
parsedLocationAnnotation,
});
await publisher.publish({
entity: entity,
directory: resultDir,
});
};
Features
Currently the build process is split up in these three stages.
- Preparers
- Generators
- Publishers
Preparers read your entity data and creates a working directory with your documentation source code. For example if you have set your backstage.io/techdocs-ref to github:https://github.com/backstage/backstage.git it will clone that repository to a temp folder and pass that on to the generator.
Generators takes the prepared source and runs the techdocs-container on it. It then passes on the output folder of that build to the publisher.
Publishers gets a folder path from the generator and publish it to your storage solution. Read documentation to know more about configuring storage solutions. http://backstage.io/docs/features/techdocs/configuration
Any of these can be extended. We want to extend our support to most of the storage providers (Publishers) and source code host providers (Preparers).