Merge pull request #538 from algorandfoundation/feat/add-examples-to-docs

Feat/add examples to docs

Author: lempira

.github/workflows/pr.yml

@@ -60,7 +60,7 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Build package
+      - name: Build
         run: npm run build
 
       - name: Start LocalNet

docs/astro.config.mjs

@@ -88,6 +88,22 @@ export default defineConfig({
           collapsed: true,
           autogenerate: { directory: 'migration' },
         },
+        {
+          label: 'Examples',
+          collapsed: true,
+          items: [
+            { label: 'Overview', link: '/examples/' },
+            { label: 'ABI Encoding', link: '/examples/abi/' },
+            { label: 'Mnemonic Utilities', link: '/examples/algo25/' },
+            { label: 'Algod Client', link: '/examples/algod-client/' },
+            { label: 'Algorand Client', link: '/examples/algorand-client/' },
+            { label: 'Common Utilities', link: '/examples/common/' },
+            { label: 'Indexer Client', link: '/examples/indexer-client/' },
+            { label: 'KMD Client', link: '/examples/kmd-client/' },
+            { label: 'Testing', link: '/examples/testing/' },
+            { label: 'Transactions', link: '/examples/transact/' },
+          ],
+        },
         typeDocSidebarGroup,
       ],
     }),

docs/src/content.config.ts

@@ -1,7 +1,23 @@
-import { defineCollection } from 'astro:content';
+import { defineCollection, z } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
+import { examplesLoader } from './loaders/examples-loader';
 
 export const collections = {
 	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+	examples: defineCollection({
+		loader: examplesLoader(),
+		schema: z.object({
+			id: z.string(),
+			title: z.string(),
+			description: z.string(),
+			prerequisites: z.string(),
+			code: z.string(),
+			category: z.string(),
+			categoryLabel: z.string(),
+			order: z.number(),
+			filename: z.string(),
+			runCommand: z.string(),
+		}),
+	}),
 };

docs/src/loaders/examples-loader.ts

@@ -0,0 +1,219 @@
+import type { Loader } from 'astro/loaders'
+import fs from 'node:fs'
+import path from 'node:path'
+
+type ExampleEntry = {
+  id: string
+  title: string
+  description: string
+  prerequisites: string
+  code: string
+  category: string
+  categoryLabel: string
+  order: number
+  filename: string
+  runCommand: string
+}
+
+interface CategoryMeta {
+  label: string
+  description: string
+  slug: string
+}
+
+const CATEGORIES: Record<string, CategoryMeta> = {
+  abi: {
+    label: 'ABI Encoding',
+    description: 'ABI type parsing, encoding, and decoding following the ARC-4 specification.',
+    slug: 'abi',
+  },
+  algo25: {
+    label: 'Mnemonic Utilities',
+    description: 'Mnemonic and seed conversion utilities following the Algorand 25-word mnemonic standard.',
+    slug: 'algo25',
+  },
+  algod_client: {
+    label: 'Algod Client',
+    description: 'Algorand node operations and queries using the AlgodClient.',
+    slug: 'algod-client',
+  },
+  algorand_client: {
+    label: 'Algorand Client',
+    description: 'High-level AlgorandClient API for simplified blockchain interactions.',
+    slug: 'algorand-client',
+  },
+  common: {
+    label: 'Common Utilities',
+    description: 'Utility functions and helpers.',
+    slug: 'common',
+  },
+  indexer_client: {
+    label: 'Indexer Client',
+    description: 'Blockchain data queries using the IndexerClient.',
+    slug: 'indexer-client',
+  },
+  kmd_client: {
+    label: 'KMD Client',
+    description: 'Key Management Daemon operations for wallet and key management.',
+    slug: 'kmd-client',
+  },
+  testing: {
+    label: 'Testing',
+    description: 'Testing utilities for mock server setup and Vitest integration.',
+    slug: 'testing',
+  },
+  transact: {
+    label: 'Transactions',
+    description: 'Low-level transaction construction and signing.',
+    slug: 'transact',
+  },
+}
+
+function lineSeparator(text: string, isBullet: boolean, lastWasBullet: boolean): string {
+  if (!text) return ''
+  if (isBullet || lastWasBullet) return '\n'
+  return ' '
+}
+
+function parseJSDoc(content: string): { title: string; description: string; prerequisites: string } {
+  const jsdocMatch = content.match(/\/\*\*\n([\s\S]*?)\*\//)
+
+  if (!jsdocMatch) {
+    return { title: 'Example', description: '', prerequisites: '' }
+  }
+
+  const jsdocContent = jsdocMatch[1]
+
+  // Extract title from "Example: Title" line
+  const titleMatch = jsdocContent.match(/\*\s*Example:\s*(.+)/)
+  const title = titleMatch?.[1]?.trim() || 'Example'
+
+  // Extract description - lines after title until Prerequisites or end
+  const lines = jsdocContent.split('\n').map((line) => line.replace(/^\s*\*\s?/, '').trim())
+
+  let description = ''
+  let prerequisites = ''
+  let inPrerequisites = false
+  let lastLineWasBullet = false
+
+  for (const line of lines) {
+    if (line.startsWith('Example:')) continue
+
+    if (line.toLowerCase().startsWith('prerequisites:') || line.toLowerCase() === 'prerequisites') {
+      inPrerequisites = true
+      lastLineWasBullet = false
+      const prereqContent = line.replace(/prerequisites:?\s*/i, '').trim()
+      if (prereqContent) prerequisites = prereqContent
+      continue
+    }
+
+    if (line.startsWith('@')) continue
+
+    if (!line) {
+      lastLineWasBullet = false
+      if (inPrerequisites) {
+        if (prerequisites) prerequisites += '\n'
+      } else if (description) {
+        description += '\n'
+      }
+      continue
+    }
+
+    const isBullet = line.startsWith('-') || line.startsWith('•')
+    if (inPrerequisites) {
+      prerequisites += lineSeparator(prerequisites, isBullet, lastLineWasBullet) + line
+    } else {
+      description += lineSeparator(description, isBullet, lastLineWasBullet) + line
+    }
+    lastLineWasBullet = isBullet
+  }
+
+  return {
+    title,
+    description: description.trim(),
+    prerequisites: prerequisites.trim() || 'LocalNet running (`algokit localnet start`)',
+  }
+}
+
+/**
+ * Extract order number from filename (e.g., "01-example.ts" -> 1)
+ */
+function extractOrder(filename: string): number {
+  const match = filename.match(/^(\d+)-/)
+  return match ? parseInt(match[1], 10) : 999
+}
+
+function createSlug(filename: string): string {
+  return filename.replace(/\.ts$/, '').replace(/_/g, '-')
+}
+
+export function examplesLoader(): Loader {
+  return {
+    name: 'examples-loader',
+    load: async ({ store, logger }) => {
+      const examplesDir = path.resolve(process.cwd(), '..', 'examples')
+
+      logger.info(`Loading examples from ${examplesDir}`)
+
+      if (!fs.existsSync(examplesDir)) {
+        logger.error(`Examples directory not found: ${examplesDir}`)
+        return
+      }
+
+      const entries: ExampleEntry[] = []
+
+      for (const [categoryDir, meta] of Object.entries(CATEGORIES)) {
+        const categoryPath = path.join(examplesDir, categoryDir)
+
+        if (!fs.existsSync(categoryPath)) {
+          logger.warn(`Category directory not found: ${categoryPath}`)
+          continue
+        }
+
+        const files = fs.readdirSync(categoryPath).filter((f) => f.endsWith('.ts') && !f.startsWith('_'))
+
+        for (const filename of files) {
+          const filePath = path.join(categoryPath, filename)
+          const content = fs.readFileSync(filePath, 'utf-8')
+          const { title, description, prerequisites } = parseJSDoc(content)
+          const order = extractOrder(filename)
+          const slug = createSlug(filename)
+
+          const entry: ExampleEntry = {
+            id: `${meta.slug}/${slug}`,
+            title,
+            description,
+            prerequisites,
+            code: content,
+            category: categoryDir,
+            categoryLabel: meta.label,
+            order,
+            filename,
+            runCommand: `npm run example ${categoryDir}/${filename}`,
+          }
+
+          entries.push(entry)
+        }
+      }
+
+      entries.sort((a, b) => {
+        if (a.category !== b.category) {
+          return a.category.localeCompare(b.category)
+        }
+        return a.order - b.order
+      })
+
+      logger.info(`Found ${entries.length} examples across ${Object.keys(CATEGORIES).length} categories`)
+
+      for (const entry of entries) {
+        store.set({
+          id: entry.id,
+          data: entry,
+        })
+      }
+    },
+  }
+}
+
+export { CATEGORIES }
+export type { ExampleEntry, CategoryMeta }

docs/src/pages/examples/[...slug].astro

@@ -0,0 +1,110 @@
+---
+import { getCollection } from 'astro:content'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+import { Code } from '@astrojs/starlight/components'
+import { CATEGORIES } from '../../loaders/examples-loader'
+
+export async function getStaticPaths() {
+  const examples = await getCollection('examples')
+  return examples.map((example) => ({
+    params: { slug: example.id },
+    props: { example },
+  }))
+}
+
+const { example } = Astro.props
+const { title, description, prerequisites, code, category, categoryLabel, filename, runCommand } = example.data
+
+// Get category meta for breadcrumb
+const categoryMeta = CATEGORIES[category]
+const categorySlug = categoryMeta?.slug || category
+
+// Build sidebar for this example
+const allExamples = await getCollection('examples')
+const categoryExamples = allExamples
+  .filter((e) => e.data.category === category)
+  .sort((a, b) => a.data.order - b.data.order)
+
+// GitHub source URL
+const githubUrl = `https://github.com/algorandfoundation/algokit-utils-ts/blob/main/examples/${category}/${filename}`
+---
+
+<StarlightPage
+  frontmatter={{
+    title: title,
+    description: description,
+  }}
+  headings={[
+    { depth: 2, text: 'Description', slug: 'description' },
+    { depth: 2, text: 'Prerequisites', slug: 'prerequisites' },
+    { depth: 2, text: 'Run This Example', slug: 'run-this-example' },
+    { depth: 2, text: 'Code', slug: 'code' },
+  ]}
+>
+  <p><a href={`/algokit-utils-ts/examples/${categorySlug}/`}>&larr; Back to {categoryLabel}</a></p>
+
+  <h2 id="description">Description</h2>
+  {(() => {
+    const text = description || 'This example demonstrates usage of the AlgoKit Utils TypeScript library.'
+    const lines = text.split('\n')
+    const elements: any[] = []
+    let bulletBuffer: string[] = []
+
+    const flushBullets = () => {
+      if (bulletBuffer.length > 0) {
+        elements.push(<ul>{bulletBuffer.map((b) => <li set:html={b} />)}</ul>)
+        bulletBuffer = []
+      }
+    }
+
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+      if (/^[-•]\s/.test(trimmed)) {
+        bulletBuffer.push(trimmed.replace(/^[-•]\s*/, ''))
+      } else {
+        flushBullets()
+        elements.push(<p set:html={trimmed} />)
+      }
+    }
+    flushBullets()
+    return elements
+  })()}
+
+  <h2 id="prerequisites">Prerequisites</h2>
+  <ul>
+    {
+      prerequisites.split('\n').map((prereq) => {
+        const text = prereq.replace(/^[-•]\s*/, '').trim()
+        return text ? <li set:html={text} /> : null
+      })
+    }
+  </ul>
+
+  <h2 id="run-this-example">Run This Example</h2>
+  <p>From the repository root:</p>
+  <Code code={`cd examples\n${runCommand}`} lang="bash" />
+
+  <h2 id="code">Code</h2>
+  <p>
+    <a href={githubUrl} target="_blank" rel="noopener noreferrer">View source on GitHub &rarr;</a>
+  </p>
+  <Code code={code} lang="typescript" title={filename} />
+
+  <hr />
+
+  <h3>Other examples in {categoryLabel}</h3>
+  <ul>
+    {
+      categoryExamples.map((e) => (
+        <li>
+          {e.id === example.id ? (
+            <strong>{e.data.title}</strong>
+          ) : (
+            <a href={`/algokit-utils-ts/examples/${e.id}/`}>{e.data.title}</a>
+          )}
+        </li>
+      ))
+    }
+  </ul>
+</StarlightPage>