TechDocs integration - MkDocs setup and publishing pipeline

[arjunmehta-git]

TechDocs needs to be wired up end-to-end before we go live:

1. Build strategy: builder: local vs external. For v1 let's use external (pre-built docs pushed to S3) - avoids Backstage needing docker runtime.

2. Storage: S3 bucket per environment (dev/prod). Each service's docs stored under <entity-namespace>/<entity-kind>/<entity-name>/.

3. Publishing pipeline: GitHub Actions workflow that runs techdocs-cli generate and techdocs-cli publish on merge to main for any repo with a catalog-info.yaml + docs/ directory.

4. mkdocs.yml template: Standard config with material theme, search plugin, and the techdocs plugin.

Tracking setup work here.

[miacycle]

For the S3 bucket - enable versioning and set a lifecycle rule to expire old doc versions after 90 days. TechDocs can generate a lot of objects if services have large docs.

Also: the publish workflow needs the TECHDOCS_S3_BUCKET_NAME and AWS_ROLE_ARN as repo secrets. Should we document the setup steps for teams, or create a shared GitHub Actions callable workflow they just invoke?

[sarajkrishnasingh]

Callable workflow (reusable workflow) is the right answer. Teams reference it with a uses: step. One source of truth, no copy-paste. We just need to make it available in a central repo - the platform repo seems right.