bsdoc

A Go CLI tool that uses GitHub Copilot to generate detailed Backstage catalog documentation for your projects.

Features

• 🤖 AI-Powered: Leverages GitHub Copilot SDK to intelligently analyze your project
• 📝 Backstage Integration: Generates compliant catalog-info.yaml files
• 🔍 Smart Analysis: Automatically detects project type, language, and structure
• ⚡ Fast: Built with Go for high performance

Installation

Homebrew

brew tap grahambrooks/bsdoc https://github.com/grahambrooks/bsdoc
brew install bsdoc

To upgrade to the latest release:

brew update && brew upgrade bsdoc

Go

go install github.com/grahambrooks/bsdoc/cmd/bsdoc@latest

Pre-built binaries

Download a release archive for your OS/arch from the releases page and place the bsdoc binary on your PATH.

Usage

Generate Backstage Documentation

Generate a catalog-info.yaml file for your current project:

bsdoc generate

Specify a custom output path:

bsdoc generate --output /path/to/catalog-info.yaml

Generate documentation for a specific project:

bsdoc generate --path /path/to/project

Version

bsdoc version

Development

Build

go build -o bin/bsdoc ./cmd/bsdoc

Run

go run ./cmd/bsdoc

Test

go test ./...

Releases

Releases are produced automatically by .github/workflows/release.yml on every push to main (and on manual workflow_dispatch). The workflow:

1. Runs go test ./....
2. Computes a CalVer version of the form YYYY.M.D, appending .N when more than one release is cut on the same day (e.g. 2026.5.8, 2026.5.8.1, 2026.5.8.2).
3. Cross-compiles bsdoc for linux/amd64, linux/arm64, darwin/amd64, and darwin/arm64, stamping the version into the binary via -ldflags "-X main.version=$VERSION".
4. Tags the commit vYYYY.M.D[.N], publishes a GitHub Release with the tarballs and a SHA256SUMS file.
5. Regenerates Formula/bsdoc.rb with the new version and per-platform SHA256s and commits it back to main with [skip ci].

To cut a release with a specific version, run the workflow manually from the Actions tab and provide an override (e.g. 2026.5.8.3).