Add a TechDocs site for recurring-events #65

Closed
opened 2026-11-21 23:01:18 +00:00 by martin · 0 comments
Owner

Summary

Add a repository-owned TechDocs site for the recurring-events API so the service's documentation is maintained alongside its OpenAPI contract and Backstage descriptor.

Context

This repository now defines the recurring-events Component and API in catalog-info.yaml, but it has no TechDocs source. Personal/backstage#25 tracks the portal-side rendering, search, and hosted-storage/access plan.

Scope

  • Add an MkDocs configuration and useful documentation pages for the API and service.
  • Annotate the Component with backstage.io/techdocs-ref: dir:..
  • Add reproducible Nix development-shell commands to build and preview the docs.
  • Document how to author, preview, and troubleshoot the docs.
  • Keep documentation and build configuration free of credentials; do not change openapi.yaml or API runtime code.

Acceptance criteria

  • just docs builds the documentation successfully from this repository.
  • The recurring-events Component's catalog descriptor points TechDocs at the repository docs.
  • just docs-serve previews the docs locally, and the README explains authoring, preview, and troubleshooting.
  • Documentation contains no credentials or private values.
  • Personal/backstage#25 verifies Backstage rendering/search and documents hosted publishing and private-document access.
## Summary Add a repository-owned TechDocs site for the recurring-events API so the service's documentation is maintained alongside its OpenAPI contract and Backstage descriptor. ## Context This repository now defines the recurring-events Component and API in `catalog-info.yaml`, but it has no TechDocs source. Personal/backstage#25 tracks the portal-side rendering, search, and hosted-storage/access plan. ## Scope - Add an MkDocs configuration and useful documentation pages for the API and service. - Annotate the Component with `backstage.io/techdocs-ref: dir:.`. - Add reproducible Nix development-shell commands to build and preview the docs. - Document how to author, preview, and troubleshoot the docs. - Keep documentation and build configuration free of credentials; do not change `openapi.yaml` or API runtime code. ## Acceptance criteria - [ ] `just docs` builds the documentation successfully from this repository. - [ ] The recurring-events Component's catalog descriptor points TechDocs at the repository docs. - [ ] `just docs-serve` previews the docs locally, and the README explains authoring, preview, and troubleshooting. - [ ] Documentation contains no credentials or private values. ## Related - Personal/backstage#25 verifies Backstage rendering/search and documents hosted publishing and private-document access.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/recurring-events#65
No description provided.