techdocs
Builds a repository's TechDocs site in CI and publishes it to S3-compatiblestorage (MinIO), so Backstage runs with `techdocs.builder: external` and
only reads the finished HTML instead of running mkdocs in its own pod.
The site is built with `techdocs-cli generate --no-docker` (mkdocs +
mkdocs-techdocs-core) and uploaded with `techdocs-cli publish
--publisher-type awsS3` to ////, the path
Backstage's awsS3 publisher reads.
Functions:
- Generate: builds the site of a source directory
- Entity: reads // from catalog-info.yaml
- Publish: uploads a generated site for an entity
- GenerateAndPublish: all of the above in one call
Installation
dagger install github.com/stuttgart-things/dagger/techdocs@v0.138.0Entrypoint
Return Type
TechdocsExample
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
func (m *MyModule) Example() *dagger.Techdocs {
return dag.
Techdocs()
}@function
def example() -> dagger.Techdocs:
return (
dag.techdocs()
)@func()
example(): Techdocs {
return dag
.techdocs()
}Types
Techdocs 🔗
baseImage() 🔗
Return Type
String !Example
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
base-imagefunc (m *MyModule) Example(ctx context.Context) string {
return dag.
Techdocs().
Baseimage(ctx)
}@function
async def example() -> str:
return await (
dag.techdocs()
.baseimage()
)@func()
async example(): Promise<string> {
return dag
.techdocs()
.baseImage()
}entity() 🔗
Entity returns // of the entity in catalogFile that carries the backstage.io/techdocs-ref annotation – the path Backstage looks up the docs under. The namespace defaults to “default”.
Return Type
String !Arguments
| Name | Type | Default Value | Description |
|---|---|---|---|
| src | Directory ! | - | Repository directory containing catalogFile |
| catalogFile | String | "catalog-info.yaml" | Catalog file inside src to read the entity from |
Example
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
entity --src DIR_PATHfunc (m *MyModule) Example(ctx context.Context, src *dagger.Directory) string {
return dag.
Techdocs().
Entity(ctx, src)
}@function
async def example(src: dagger.Directory) -> str:
return await (
dag.techdocs()
.entity(src)
)@func()
async example(src: Directory): Promise<string> {
return dag
.techdocs()
.entity(src)
}generate() 🔗
Generate builds the TechDocs site of src (the directory holding mkdocs.yml) and returns it.
Return Type
Directory !Arguments
| Name | Type | Default Value | Description |
|---|---|---|---|
| src | Directory ! | - | Repository (or docs) directory containing mkdocs.yml |
| sourceDir | String | "." | Directory of mkdocs.yml inside src |
Example
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
generate --src DIR_PATHfunc (m *MyModule) Example(src *dagger.Directory) *dagger.Directory {
return dag.
Techdocs().
Generate(src)
}@function
def example(src: dagger.Directory) -> dagger.Directory:
return (
dag.techdocs()
.generate(src)
)@func()
example(src: Directory): Directory {
return dag
.techdocs()
.generate(src)
}generateAndPublish() 🔗
GenerateAndPublish builds the site of src and publishes it. The entity is read from catalog-info.yaml unless given.
Return Type
String !Arguments
| Name | Type | Default Value | Description |
|---|---|---|---|
| src | Directory ! | - | Repository directory containing mkdocs.yml and catalog-info.yaml |
| bucket | String ! | - | Bucket Backstage reads (techdocs.publisher.awsS3.bucketName) |
| endpoint | String ! | - | S3 endpoint, e.g. https://minio.example.com |
| accessKey | Secret ! | - | S3 access key of a user that may write to bucket |
| secretKey | Secret ! | - | S3 secret key |
| entity | String | - | Entity as //; read from catalogFile if empty |
| catalogFile | String | "catalog-info.yaml" | Catalog file inside src to read the entity from |
| sourceDir | String | "." | Directory of mkdocs.yml inside src |
| region | String | "us-east-1" | Region; MinIO accepts any value |
| caCert | File | - | PEM CA certificate for an endpoint signed by a private CA |
Example
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
generate-and-publish --src DIR_PATH --bucket string --endpoint string --access-key env:MYSECRET --secret-key env:MYSECRETfunc (m *MyModule) Example(ctx context.Context, src *dagger.Directory, bucket string, endpoint string, accessKey *dagger.Secret, secretKey *dagger.Secret) string {
return dag.
Techdocs().
Generateandpublish(ctx, src, bucket, endpoint, accessKey, secretKey)
}@function
async def example(src: dagger.Directory, bucket: str, endpoint: str, accesskey: dagger.Secret, secretkey: dagger.Secret) -> str:
return await (
dag.techdocs()
.generateandpublish(src, bucket, endpoint, accesskey, secretkey)
)@func()
async example(src: Directory, bucket: string, endpoint: string, accessKey: Secret, secretKey: Secret): Promise<string> {
return dag
.techdocs()
.generateAndPublish(src, bucket, endpoint, accessKey, secretKey)
}publish() 🔗
Publish uploads a site built by Generate to an S3-compatible bucket, under the path Backstage reads for entity. Stale files of a previous publish of the same entity are removed.
Return Type
String !Arguments
| Name | Type | Default Value | Description |
|---|---|---|---|
| site | Directory ! | - | Site directory returned by Generate |
| entity | String ! | - | Entity as //, e.g. default/component/flux |
| bucket | String ! | - | Bucket Backstage reads (techdocs.publisher.awsS3.bucketName) |
| endpoint | String ! | - | S3 endpoint, e.g. https://minio.example.com |
| accessKey | Secret ! | - | S3 access key of a user that may write to bucket |
| secretKey | Secret ! | - | S3 secret key |
| region | String | "us-east-1" | Region; MinIO accepts any value |
| caCert | File | - | PEM CA certificate for an endpoint signed by a private CA |
Example
dagger -m github.com/stuttgart-things/dagger/techdocs@92f91c00530505785285858f86af64e2fff02aff call \
publish --site DIR_PATH --entity string --bucket string --endpoint string --access-key env:MYSECRET --secret-key env:MYSECRETfunc (m *MyModule) Example(ctx context.Context, site *dagger.Directory, entity string, bucket string, endpoint string, accessKey *dagger.Secret, secretKey *dagger.Secret) string {
return dag.
Techdocs().
Publish(ctx, site, entity, bucket, endpoint, accessKey, secretKey)
}@function
async def example(site: dagger.Directory, entity: str, bucket: str, endpoint: str, accesskey: dagger.Secret, secretkey: dagger.Secret) -> str:
return await (
dag.techdocs()
.publish(site, entity, bucket, endpoint, accesskey, secretkey)
)@func()
async example(site: Directory, entity: string, bucket: string, endpoint: string, accessKey: Secret, secretKey: Secret): Promise<string> {
return dag
.techdocs()
.publish(site, entity, bucket, endpoint, accessKey, secretKey)
}