docs(metrics): automate usage metrics collection and publish it in the docs site

.github/workflows/usage-metrics.yml

@@ -0,0 +1,85 @@
+name: Update Usage Metrics
+
+on:
+  schedule:
+    # Run monthly on the 1st at 9 AM UTC
+    - cron: '0 9 1 * *'
+  workflow_dispatch:
+    inputs:
+      versions:
+        description: 'Comma-separated versions to query (leave empty for all versions)'
+        required: false
+        default: ''
+
+permissions:
+  contents: write
+
+jobs:
+  collect-metrics:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up Go
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
+        with:
+          go-version-file: 'usage-metrics/go.mod'
+
+      - name: Query versions
+        id: query
+        working-directory: usage-metrics
+        run: |
+          # Get versions to query
+          VERSIONS="${{ github.event.inputs.versions }}"
+          if [ -z "$VERSIONS" ]; then
+            # Get all versions from v0.13.0 to latest from the main repository
+            VERSIONS=$(git ls-remote --tags https://github.com/testcontainers/testcontainers-go.git | \
+              grep -E 'refs/tags/v0\.[0-9]+\.[0-9]+$' | \
+              sed 's|.*refs/tags/||' | \
+              sort -V | \
+              awk '/v0.13.0/,0' | \
+              tr '\n' ',' | \
+              sed 's/,$//')
+          fi
+
+          echo "Querying versions: $VERSIONS"
+
+          # Build version flags
+          VERSION_FLAGS=""
+          IFS=',' read -ra VERSION_ARRAY <<< "$VERSIONS"
+          for version in "${VERSION_ARRAY[@]}"; do
+            version=$(echo "$version" | xargs) # trim whitespace
+            if [ -z "$version" ]; then
+              continue
+            fi
+            VERSION_FLAGS="$VERSION_FLAGS -version $version"
+          done
+
+          # Query all versions in a single command
+          go run collect-metrics.go $VERSION_FLAGS -csv "../../docs/usage-metrics.csv"
+
+      - name: Create Pull Request
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/usage-metrics.csv
+
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+            exit 0
+          fi
+
+          # Create a new branch for the PR
+          DATE=$(date +%Y-%m-%d)
+          BRANCH_NAME="chore/update-usage-metrics-$DATE"
+          git checkout -b "$BRANCH_NAME"
+
+          git commit -m "chore(metrics): update usage metrics ($DATE)"
+          git push -u origin "$BRANCH_NAME"
+
+          # Create PR using gh CLI
+          gh pr create \
+            --title "chore: update usage metrics ($DATE)" \
+            --body "Automated update of usage metrics data. This PR updates the usage metrics CSV file with the latest GitHub usage data for testcontainers-go versions." \
+            --base main

.gitignore

@@ -23,3 +23,6 @@ TEST-*.xml
 
 # Coverage files
 coverage.out
+
+# Usage metrics script binary
+usage-metrics/scripts/collect-metrics

docs/css/usage-metrics.css

@@ -0,0 +1,111 @@
+/* Usage Metrics Dashboard Styles */
+
+/* Expand content to use full available width - only on usage metrics page */
+body:has(#content.usage-metrics) .md-content__inner,
+body:has(.stats-grid) .md-content__inner {
+    max-width: none !important;
+    margin: 0 !important;
+}
+
+body:has(#content.usage-metrics) .md-content__inner > article,
+body:has(.stats-grid) .md-content__inner > article {
+    padding: 0 2rem;
+}
+
+@media screen and (min-width: 76.25em) {
+    body:has(#content.usage-metrics) .md-content__inner > article,
+    body:has(.stats-grid) .md-content__inner > article {
+        padding: 0 4rem;
+    }
+}
+
+@media screen and (min-width: 100em) {
+    body:has(#content.usage-metrics) .md-content__inner > article,
+    body:has(.stats-grid) .md-content__inner > article {
+        padding: 0 6rem;
+    }
+}
+
+.stats-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+    gap: 20px;
+    margin-bottom: 40px;
+}
+
+.stat-card {
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 25px;
+    border-radius: 15px;
+    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);
+}
+
+.stat-label {
+    font-size: 0.9rem;
+    opacity: 0.9;
+    margin-bottom: 5px;
+}
+
+.stat-value {
+    font-size: 2.5rem;
+    font-weight: bold;
+}
+
+.chart-container {
+    background: white;
+    border-radius: 15px;
+    padding: 30px;
+    margin-bottom: 30px;
+    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+}
+
+.chart-title {
+    font-size: 1.5rem;
+    color: #333;
+    margin-bottom: 20px;
+    font-weight: 600;
+}
+
+.chart-container canvas {
+    max-height: 400px;
+}
+
+.loading {
+    text-align: center;
+    padding: 40px;
+    color: #666;
+    font-size: 1.2rem;
+}
+
+.error {
+    background: #fee;
+    border: 1px solid #fcc;
+    border-radius: 10px;
+    padding: 20px;
+    color: #c33;
+    margin: 20px 0;
+}
+
+.metrics-info {
+    text-align: center;
+    margin-top: 40px;
+    padding-top: 20px;
+    border-top: 1px solid #eee;
+    color: #666;
+    font-size: 0.9rem;
+}
+
+.metrics-info p {
+    margin: 5px 0;
+}
+
+@media (max-width: 768px) {
+    .stat-value {
+        font-size: 2rem;
+    }
+
+    .chart-container {
+        padding: 20px;
+    }
+}