Docs/starlight docs

.github/actions/build-and-publish-documentation/action.yml

@@ -0,0 +1,52 @@
+name: 'Build and Publish Documentation'
+description: 'Builds Astro Starlight documentation and publishes to GitHub Pages or PR preview'
+inputs:
+  node-version:
+    description: 'Node.js version to use'
+    required: false
+    default: '22.x'
+  deployment-type:
+    description: 'Type of deployment: "release" or "pr-preview"'
+    required: true
+  pr-number:
+    description: 'Pull request number (required for pr-preview deployment)'
+    required: false
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate preview inputs
+      if: inputs.deployment-type == 'pr-preview'
+      shell: bash
+      run: |
+        if [ -z "${{ inputs.pr-number }}" ]; then
+          echo "Input 'pr-number' is required when deployment-type=pr-preview"
+          exit 1
+        fi
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Setup pnpm
+      uses: pnpm/action-setup@v4
+      with:
+        package_json_file: docs/package.json
+
+    - name: Install root dependencies
+      shell: bash
+      run: npm ci
+
+    - name: Install docs dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile --dir docs
+
+    - name: Build documentation
+      shell: bash
+      run: npm run docs:build
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/dist

.github/workflows/gh-pages.yml

@@ -1,4 +1,4 @@
-name: 'Run typedoc and publish to pages'
+name: Publish docs to GitHub Pages
 
 on:
   workflow_call:
@@ -15,21 +15,11 @@ jobs:
       - name: Checkout source code
         uses: actions/checkout@v4
 
-      - name: Use Node.js 22.x
-        uses: actions/setup-node@v4
+      - name: Build and upload docs artifact
+        uses: ./.github/actions/build-and-publish-documentation
         with:
           node-version: 22.x
-
-      - name: Npm install
-        run: npm ci --ignore-scripts
-
-      - name: Build doc
-        run: npm run script:documentation
-
-      - name: Upload to GitHub pages
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/_html
+          deployment-type: release
 
       - name: Deploy to GitHub Pages
         uses: actions/deploy-pages@v4

.github/workflows/pr.yml

@@ -1,5 +1,4 @@
 name: Pull Request
-
 on:
   pull_request:
     branches:
@@ -11,7 +10,7 @@ on:
 
 permissions:
   contents: read
-
+  
 jobs:
   build:
     name: 'Build @algorandfoundation/algorand-typescript-testing'
@@ -24,4 +23,4 @@ jobs:
       node-version: 22.x
       run-build: true
       run-commit-lint: true
-      audit-script: npm run audit
+      audit-script: npm run audit

.github/workflows/publish-devportal-docs.yml

@@ -0,0 +1,30 @@
+name: Publish DevPortal Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [docs/starlight-docs]
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: docs/package.json
+      - name: Install root dependencies
+        run: npm ci
+      - name: Build package
+        run: npm run build
+      - name: Publish DevPortal Docs
+        uses: algorandfoundation/devportal/.github/actions/publish-devportal-docs@ci/update-publish-devportal-docs-workflow
+        with:
+          docs-dir: docs

.github/workflows/release.yml

@@ -6,6 +6,7 @@ on:
       - alpha
       - main
       - release
+      - docs/starlight-docs
   workflow_dispatch:
 
 concurrency: release
@@ -61,23 +62,22 @@ jobs:
         with:
           path: artifacts
 
-      - name: Generate semantic version for @algorandfoundation/algorand-typescript-testing
-        run: npx semantic-release
-        env:
-          GITHUB_TOKEN: ${{ steps.app_token.outputs.token }}
+      # - name: Generate semantic version for @algorandfoundation/algorand-typescript-testing
+      #   run: npx semantic-release
+      #   env:
+      #     GITHUB_TOKEN: ${{ steps.app_token.outputs.token }}
 
-      - name: Publish @algorandfoundation/algorand-typescript-testing
-        uses: JS-DevTools/npm-publish@v3
-        with:
-          token: ${{ secrets.NPM_TOKEN }}
-          package: artifacts/algo-ts-testing/package.json
-          access: 'public'
-          tag: ${{ github.ref_name == 'alpha' && 'alpha' || github.ref_name == 'main' && 'beta' || github.ref_name == 'release' && 'latest' || 'pre-release' }}
+      # - name: Publish @algorandfoundation/algorand-typescript-testing
+      #   uses: JS-DevTools/npm-publish@v3
+      #   with:
+      #     token: ${{ secrets.NPM_TOKEN }}
+      #     package: artifacts/algo-ts-testing/package.json
+      #     access: 'public'
+      #     tag: ${{ github.ref_name == 'alpha' && 'alpha' || github.ref_name == 'main' && 'beta' || github.ref_name == 'release' && 'latest' || 'pre-release' }}
 
   publish-docs:
     name: Publish docs
     needs: release
-    if: github.ref_name == 'release'
     uses: ./.github/workflows/gh-pages.yml
     permissions:
       contents: read

.gitignore

@@ -42,6 +42,9 @@ node_modules/
 .yarn/install-state.gz
 .pnp.*
 
+# pnpm
+.pnpm-store/
+
 # Compiled code
 dist/
 build/
@@ -67,3 +70,6 @@ docs/_html
 
 examples/debug-out/
 examples/**/data/
+
+# AI Agents
+.codex

docs/.gitignore

@@ -0,0 +1,25 @@
+# build output
+dist/
+# generated types
+.astro/
+# generated API docs (built by starlight-typedoc)
+src/content/docs/api/
+# generated example docs (built by generate-examples-mdx.ts)
+src/content/docs/examples/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/astro.config.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+import { defineConfig } from 'astro/config'
+import starlight from '@astrojs/starlight'
+import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc'
+import remarkGithubAlerts from 'remark-github-alerts'
+import sidebarConfig from './sidebar.config.json'
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://algorandfoundation.github.io',
+  base: '/algorand-typescript-testing/',
+  trailingSlash: 'always',
+  markdown: {
+    remarkPlugins: [remarkGithubAlerts],
+  },
+  integrations: [
+    starlight({
+      title: 'Algorand TypeScript Testing',
+      favicon: '/algokit_logo.png',
+      expressiveCode: false,
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/algorandfoundation/algorand-typescript-testing' },
+        { icon: 'discord', label: 'Discord', href: 'https://discord.gg/algorand' },
+      ],
+      plugins: [
+        starlightTypeDoc({
+          entryPoints: [
+            '../src/index.ts',
+            '../src/test-transformer/jest-transformer.ts',
+            '../src/test-transformer/vitest-transformer.ts',
+            '../src/value-generators/index.ts',
+          ],
+          tsconfig: '../tsconfig.build.json',
+          output: 'api',
+          sidebar: {
+            label: 'API Reference',
+            collapsed: true,
+          },
+          typeDoc: {
+            excludeReferences: true,
+            gitRevision: 'main',
+            entryFileName: 'index',
+          },
+        }),
+      ],
+      sidebar: [...sidebarConfig, typeDocSidebarGroup],
+    }),
+  ],
+})

docs/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@algorandfoundation/algokit-typescript-testing-docs",
+  "private": true,
+  "type": "module",
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.30.3",
+  "scripts": {
+    "generate:examples": "tsx scripts/generate-examples-mdx.ts",
+    "dev": "astro dev",
+    "build": "npm run generate:examples && astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.37.6",
+    "astro": "^5.6.1",
+    "remark-github-alerts": "^0.1.1",
+    "sharp": "^0.34.2",
+    "starlight-typedoc": "^0.21.5",
+    "typedoc": "^0.28.16"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}