@shoalrun/cli 0.1.0-beta.1 → 1.0.0

package/dist/page-renderer.js

@@ -38,6 +38,8 @@ export function shareCardText(doc, config) {
     return { title, summary: String(summary), type: typeLabel(doc.frontmatter.type) };
 }
 export function typeLabel(type) {
+    if (type === 'code-reference')
+        return 'Code API reference';
     const words = String(type).split('-').filter(Boolean).map(word => word === 'api' ? 'API' : word);
     const label = words.join(' ');
     return label.charAt(0).toUpperCase() + label.slice(1);
@@ -192,6 +194,6 @@ export function buildHtmlPage(doc, tree, markdownUrl, siteTitle, navigation, exa
     const menu = side || sectionNavigation ? `<a class="mobile-menu" href="#${side ? 'docs-navigation' : 'docs-sections'}">Menu</a>` : '';
     const rail = toc || panel ? `<aside class="page-rail">${doc.endpoint ? `${panel}${toc}` : `${toc}${panel}`}</aside>` : '';
     const breadcrumbs = (shell.breadcrumbs?.length ?? 0) > 1 && !hero ? `<nav class="doc-breadcrumbs" aria-label="Breadcrumb"><ol>${shell.breadcrumbs.map((item, index) => `<li>${index === shell.breadcrumbs.length - 1 ? `<span aria-current="page">${esc(item.label)}</span>` : item.url ? `<a href="${esc(item.url)}">${esc(item.label)}</a>` : `<span>${esc(item.label)}</span>`}</li>`).join('')}</ol></nav>` : '';
-    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${publicationPicker(shell, esc)}${editionLabel && !shell.publicationChoices?.length && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? (pdfLink ? `<div class="page-formats">${pdfLink}</div>` : '') : `<div class="page-formats">${pdfAction?.placement === 'before' ? pdfLink : ''}<a class="formats" data-markdown-link href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span>${pdfAction?.placement === 'after' ? pdfLink : ''}</div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}${pdfAction?.mode === 'print' ? '<script type="module" src="/assets/print.js"></script>' : ''}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
+    const markup = `<!doctype html><html lang="${esc(doc.variant.language)}"${shell.themeCss || shell.paletteCss ? ` data-theme="${esc(shell.preset ?? 'shoal')}" data-palette="${esc(shell.palette ?? '')}"` : ''}${shell.masthead ? ` data-masthead="${esc(shell.masthead)}"` : ''}${layout === 'docs' ? '' : ` data-layout="${layout}"`}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="${shell.mode === 'system' ? 'light dark' : shell.mode ?? 'light'}">${shell.indexing === false || doc.frontmatter.seo?.noindex === true ? '<meta name="robots" content="noindex">' : ''}${shell.origin ? `<link rel="canonical" href="${esc(absolute(doc.route))}">` : ''}${shell.toggle ? '<script src="/assets/mode.js"></script>' : ''}<title>${esc(String(title))}</title>${description ? `<meta name="description" content="${esc(String(description))}">` : ''}${socialDescription ? `<meta property="og:description" content="${esc(socialDescription)}">` : ''}${social}<link rel="alternate" type="text/markdown" href="${esc(markdownUrl)}"><link rel="describedby" href="/llms.min.txt" title="Documentation index">${icons}${shell.preloadFont ? `<link rel="preload" href="/assets/fonts/${esc(shell.preloadFont)}" as="font" type="font/woff2" crossorigin>` : ''}${(shell.preloadFonts ?? []).map(font => `<link rel="preload" href="${esc(font.href)}" as="font" type="${esc(font.type)}" crossorigin>`).join('')}<link rel="stylesheet" href="/assets/site.css">${article.includes('data-theme-preview') ? '<link rel="stylesheet" href="/assets/theme-preview.css">' : ''}${shell.themeCss ? '<link rel="stylesheet" href="/assets/theme.css" data-theme-link="theme">' : ''}${shell.paletteCss ? '<link rel="stylesheet" href="/assets/palette.css" data-theme-link="palette">' : ''}${shell.badgesCss ? '<link rel="stylesheet" href="/assets/badges.css">' : ''}${shell.themeSwitcher ? `<script src="/assets/theme-switcher.js" data-themes="${esc(shell.themeSwitcher)}"></script>` : ''}${shell.fontsCss ? '<link rel="stylesheet" href="/assets/fonts.css">' : ''}${customCss ? '<link rel="stylesheet" href="/assets/project.css">' : ''}</head><body><a class="skip" href="#main">Skip to content</a>${agent.mode === 'disclosure' ? '' : agentBlock}<header class="mast"><div class="mast-inner">${shell.home ? `<a class="${brandClass}" href="/">${brand}</a>` : `<span class="${brandClass}">${brand}</span>`}${publicationPicker(shell, esc)}${editionLabel && !shell.publicationChoices?.length && (shell.publicationAlternates?.length ?? 0) < 2 ? `<span class="edition">${esc(editionLabel)}</span>` : ''}${menu}${headerTools(shell, doc.variant, esc, readerConfig)}${agent.mode === 'disclosure' ? agentBlock : ''}</div></header>${sectionNavigation}${shortcuts}<div class="layout${layout === 'docs' ? '' : ` layout-${layout}`}${rail ? ' has-rail' : ''}${panel ? ' has-examples' : ''}${doc.endpoint ? ' api-reference' : ''}"><main id="main" class="content" tabindex="-1" data-document-type="${esc(doc.frontmatter.type)}"${readerConfig ? ` data-reader-page="${esc(readerFilterAttribute(doc.readerFilters ?? {}))}"` : ''}>${breadcrumbs}${hero ? '' : `<header class="page-head"><span class="eyebrow">${esc(typeLabel(doc.frontmatter.type))}</span>${doc.endpoint ? '' : badge(doc.frontmatter.subjectLifecycle)}<h1>${esc(doc.frontmatter.title)}${doc.endpoint ? badge(doc.frontmatter.subjectLifecycle) : ''}</h1>${pageHeader && !routeSummary ? `<p class="summary">${esc(pageHeader)}</p>` : ''}${pageDates}${endpoint}${audienceBadges}</header>`}${hero ? (pdfLink ? `<div class="page-formats">${pdfLink}</div>` : '') : `<div class="page-formats">${pdfAction?.placement === 'before' ? pdfLink : ''}<a class="formats" data-markdown-link href="${esc(markdownUrl)}">Read as Markdown</a><button type="button" class="formats" data-copy-markdown hidden>Copy as Markdown</button><span role="status" data-copy-markdown-status></span>${pdfAction?.placement === 'after' ? pdfLink : ''}</div>`}${toc ? '<div class="mobile-outline-slot"></div>' : ''}${jumps}${readerBanner}<article>${article}</article></main>${rail}${side}</div>${footer}${analyticsBootstrap}${readerBootstrap}${pdfAction?.mode === 'print' ? '<script type="module" src="/assets/print.js"></script>' : ''}<script type="module" src="/assets/copy-markdown.js"></script><script type="module" src="/assets/navigation.js"></script><script type="module" src="/assets/reader.js"></script><script type="module" src="/assets/tabs.js"></script>${shell.search ? '<script type="module" src="/assets/search.js"></script>' : ''}${article.includes('data-tooltip') ? '<script type="module" src="/assets/tooltips.js"></script>' : ''}${article.includes('data-component-module') ? '<script type="module" src="/assets/components.js"></script>' : ''}${article.includes('data-file-tree') ? '<script type="module" src="/assets/file-tree.js"></script>' : ''}${article.includes('data-image-expand') ? '<script type="module" src="/assets/image-viewer.js"></script>' : ''}${article.includes('data-table-filter') || article.includes('data-definition-filter') ? '<script type="module" src="/assets/table-filter.js"></script>' : ''}${article.includes('data-walkthrough') ? '<script type="module" src="/assets/walkthrough.js"></script>' : ''}${article.includes('data-cookbook-chooser') ? '<script type="module" src="/assets/cookbook-chooser.js"></script>' : ''}${article.includes('data-theme-preview') ? '<script type="module" src="/assets/theme-preview.js"></script>' : ''}${panel ? '<script type="module" src="/assets/example-panel.js"></script>' : ''}${panel.includes('data-code-samples') ? '<script type="module" src="/assets/code-samples.js"></script>' : ''}</body></html>`;
     return basePath ? markup.replace(/((?:href|src)=")\/(assets\/|llms(?:\.min)?\.txt|apple-touch-icon\.png)/g, `$1${basePath}/$2`).replace('href="/"', `href="${basePath}/"`) : markup;
 }

package/dist/publication-render.d.ts

@@ -8,7 +8,7 @@ import type { ReaderFiltersConfig } from './reader-filters.js';
 import type { CodeHighlighter } from './highlight.js';
 import type { MaterializedPage } from './page-materialization.js';
 import type { ResolvedCompilerConfig, CompilerSiteConfig, CompilerPublicationsConfig } from './compiler-config.js';
-export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
+export declare function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, customFontPreloads, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }: {
     freshness?: Freshness;
     rendered: MaterializedPage[];
     docs: Map<string, Document>;
@@ -41,6 +41,7 @@ export declare function renderPublicationPages({ rendered, docs, relationships,
     themeSwitcherData?: string;
     generatedFontsCss?: string;
     fontsPreload?: string;
+    customFontPreloads?: import('./fonts.js').FontPreload[];
     shareFor: (doc: Document) => {
         route: string;
         generated: boolean;

package/dist/publication-render.js

@@ -12,7 +12,7 @@ import { navigationPath, navigationTab, navigationTabRecord, resolveProjectNavig
 import { outputUrl, publicTree, resolveOutputLinks } from './representation-tree.js';
 import { presetCatalog } from './palettes.js';
 const keyFor = documentKey;
-export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
+export function renderPublicationPages({ rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes, basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette, themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload, customFontPreloads, shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments, externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder, freshness }) {
     const resolvedNavigation = new Map();
     const selector = config.site.publicationSelector;
     if (selector !== undefined && (!isConfigMapping(selector) || Object.keys(selector).some(key => key !== 'showLanguage') || (selector.showLanguage !== undefined && typeof selector.showLanguage !== 'boolean')))
@@ -102,7 +102,7 @@ export function renderPublicationPages({ rendered, docs, relationships, knownOpe
             const group = variant.product === undefined ? config.site.title : config.publications.products?.[variant.product]?.label ?? variant.product;
             return [{ group, label: `${group} · ${variant.channel} · ${variant.version}${showLanguage ? ` · ${variant.language}` : ''}`, url: target.route, current: samePublication(page.doc.variant, variant) }];
         }) : [];
-        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationChoices, publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
+        page.html = buildHtmlPage(page.doc, page.htmlTree, page.doc.markdownRoute, config.site.title, navigation, page.pageExamples, page.pageShapes, highlighter, editionLabel(page.doc.variant), !!customStyleFile, { preset: themePreset, palette: palette.name, themeCss: !!themeStyleFile, paletteCss: !!generatedPaletteCss, badgesCss: !!generatedBadgeCss, themeSwitcher: themeSwitcherData, fontsCss: !!generatedFontsCss, preloadFont: fontsPreload, preloadFonts: customFontPreloads, masthead: presetCatalog.find(preset => preset.name === themePreset)?.masthead, share: shareFor(page.doc), favicon: faviconRoute, logo: logoRoute, touchIcon: !faviconRoute.endsWith('.png'), origin: siteOrigin, indexing: config.site.indexing !== false, home: hasHome, mode: colorMode, toggle: modeToggle, header, footer, search: search.provider !== 'none', publicationChoices, publicationAlternates, breadcrumbs }, page.pageCurl, page.pageSamples, { ...config, readerFilters });
     }
     return resolvedNavigation;
 }

package/dist/representation-tree.js

@@ -66,6 +66,10 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
         if (node.type === 'docReaderFilter') {
             return representation === 'markdown' ? [] : [element('div', { className: ['reader-filter-slot'], 'data-reader-filter': JSON.stringify(node.control) }, [])];
         }
+        if (node.type === 'table' && node.data?.referenceTableLabel && representation === 'html') {
+            const table = { ...node, children: node.children.flatMap(walk) };
+            return [element('div', { className: ['code-reference-table-scroll'], role: 'region', 'aria-label': node.data.referenceTableLabel, tabIndex: 0 }, [table])];
+        }
         if (node.type === 'docTable') {
             const table = node.children.flatMap(walk);
             if (representation === 'markdown')

package/examples/code-references/content/start.md

@@ -0,0 +1,53 @@
+---
+id: guide.start
+title: Python SDK
+summary: Explore a typed SDK with synchronous and async clients, models, pagination, and exceptions.
+type: guide
+slug: /
+channel: production
+version: current
+language: en
+access: { policy: public }
+---
+This example SDK manages records. Its reference pages are generated from Python source and docstrings, then rendered with Shoalrun's normal theme, navigation, search, and Markdown output.
+
+The sample client stores records in memory. It doesn't connect to a live service.
+
+## Fetch a typed record
+
+```python
+from orchard import Client
+
+client = Client("demo-key")
+record = client.fetch("rec_42")
+print(record.title)
+```
+
+Read [Client](doc:reference.client) for configuration and [fetch](doc:reference.fetch) for its typed and raw-response overloads.
+
+## Work with more than one page
+
+```python
+from orchard import RecordStatus
+
+for record in client.iter_records(page_size=50, status=RecordStatus.READY):
+    print(record.id, record.title)
+```
+
+Choose [list_records](doc:reference.Client.list_records) when your application needs explicit cursor control, or [Page.map](doc:reference.pagination.Page.map) to transform a response without losing its pagination metadata.
+
+## Use an async client
+
+```python
+from orchard import AsyncClient
+
+client = AsyncClient("demo-key")
+async for record in client.iter_records(page_size=50):
+    print(record.title)
+```
+
+Browse [AsyncClient](doc:reference.AsyncClient), [Record](doc:reference.models.Record), and the [typed exceptions](doc:reference.errors) to see how the generated reference fits together.
+
+## Choose how to browse
+
+Read the [Client class with member details inline](doc:reference.client), or open the [complete Python SDK reference](doc:reference.complete) to browse everything on one page. The example uses `layout: classes` and enables `singlePage` in its catalog configuration. Individual symbol links remain available.

package/examples/code-references/docs.config.yaml

@@ -0,0 +1,262 @@
+schemaVersion: 1
+site:
+  title: Python SDK documentation
+publications:
+  channels:
+    production: {}
+  versions:
+    current: {}
+  defaults:
+    channel: production
+    version: current
+    language: en
+  enabled:
+    - channel: production
+      version: current
+      language: en
+codeReferences:
+  sdk:
+    source:
+      kind: file
+      path: ./reference.json
+    symbols:
+      orchard:
+        documentId: reference.orchard
+        slug: /reference/orchard
+      orchard.client:
+        documentId: reference.clients
+        slug: /reference/clients
+      orchard.client.AsyncClient:
+        documentId: reference.AsyncClient
+        slug: /reference/async-client
+      orchard.client.AsyncClient.__init__:
+        documentId: reference.AsyncClient.__init__
+        slug: /reference/async-client/constructor
+      orchard.client.AsyncClient.fetch:
+        documentId: reference.AsyncClient.fetch
+        slug: /reference/async-client/fetch
+      orchard.client.AsyncClient.iter_records:
+        documentId: reference.AsyncClient.iter_records
+        slug: /reference/async-client/iter-records
+      orchard.client.Client:
+        documentId: reference.client
+        slug: /reference/client
+      orchard.client.Client.__init__:
+        documentId: reference.Client.__init__
+        slug: /reference/client/constructor
+      orchard.client.Client.base_url:
+        documentId: reference.Client.base_url
+        slug: /reference/client/base-url
+      orchard.client.Client.bulk_create:
+        documentId: reference.Client.bulk_create
+        slug: /reference/client/bulk-create
+      orchard.client.Client.create_record:
+        documentId: reference.Client.create_record
+        slug: /reference/client/create-record
+      orchard.client.Client.fetch:
+        documentId: reference.fetch
+        slug: /reference/client/fetch
+      orchard.client.Client.iter_records:
+        documentId: reference.Client.iter_records
+        slug: /reference/client/iter-records
+      orchard.client.Client.list_records:
+        documentId: reference.Client.list_records
+        slug: /reference/client/list-records
+      orchard.client.Client.max_retries:
+        documentId: reference.Client.max_retries
+        slug: /reference/client/max-retries
+      orchard.client.Client.timeout:
+        documentId: reference.Client.timeout
+        slug: /reference/client/timeout
+      orchard.errors:
+        documentId: reference.errors
+        slug: /reference/errors
+      orchard.errors.APIError:
+        documentId: reference.errors.APIError
+        slug: /reference/errors/apierror
+      orchard.errors.APIError.__init__:
+        documentId: reference.errors.APIError.__init__
+        slug: /reference/errors/apierror/constructor
+      orchard.errors.APIError.request_id:
+        documentId: reference.errors.APIError.request_id
+        slug: /reference/errors/apierror/request-id
+      orchard.errors.AuthenticationError:
+        documentId: reference.errors.AuthenticationError
+        slug: /reference/errors/authenticationerror
+      orchard.errors.NotFoundError:
+        documentId: reference.errors.NotFoundError
+        slug: /reference/errors/notfounderror
+      orchard.errors.RateLimitError:
+        documentId: reference.errors.RateLimitError
+        slug: /reference/errors/ratelimiterror
+      orchard.errors.RateLimitError.__init__:
+        documentId: reference.errors.RateLimitError.__init__
+        slug: /reference/errors/ratelimiterror/constructor
+      orchard.errors.RateLimitError.retry_after:
+        documentId: reference.errors.RateLimitError.retry_after
+        slug: /reference/errors/ratelimiterror/retry-after
+      orchard.models:
+        documentId: reference.models
+        slug: /reference/models
+      orchard.models.Record:
+        documentId: reference.models.Record
+        slug: /reference/models/record
+      orchard.models.Record.created_at:
+        documentId: reference.models.Record.created_at
+        slug: /reference/models/record/created-at
+      orchard.models.Record.id:
+        documentId: reference.models.Record.id
+        slug: /reference/models/record/id
+      orchard.models.Record.labels:
+        documentId: reference.models.Record.labels
+        slug: /reference/models/record/labels
+      orchard.models.Record.status:
+        documentId: reference.models.Record.status
+        slug: /reference/models/record/status
+      orchard.models.Record.title:
+        documentId: reference.models.Record.title
+        slug: /reference/models/record/title
+      orchard.models.Record.to_dict:
+        documentId: reference.models.Record.to_dict
+        slug: /reference/models/record/to-dict
+      orchard.models.RecordDict:
+        documentId: reference.models.RecordDict
+        slug: /reference/models/recorddict
+      orchard.models.RecordDict.id:
+        documentId: reference.models.RecordDict.id
+        slug: /reference/models/recorddict/id
+      orchard.models.RecordDict.status:
+        documentId: reference.models.RecordDict.status
+        slug: /reference/models/recorddict/status
+      orchard.models.RecordDict.title:
+        documentId: reference.models.RecordDict.title
+        slug: /reference/models/recorddict/title
+      orchard.models.RecordInput:
+        documentId: reference.models.RecordInput
+        slug: /reference/models/recordinput
+      orchard.models.RecordInput.labels:
+        documentId: reference.models.RecordInput.labels
+        slug: /reference/models/recordinput/labels
+      orchard.models.RecordInput.title:
+        documentId: reference.models.RecordInput.title
+        slug: /reference/models/recordinput/title
+      orchard.models.RecordStatus:
+        documentId: reference.models.RecordStatus
+        slug: /reference/models/recordstatus
+      orchard.models.RecordStatus.FAILED:
+        documentId: reference.models.RecordStatus.FAILED
+        slug: /reference/models/recordstatus/failed
+      orchard.models.RecordStatus.PENDING:
+        documentId: reference.models.RecordStatus.PENDING
+        slug: /reference/models/recordstatus/pending
+      orchard.models.RecordStatus.READY:
+        documentId: reference.models.RecordStatus.READY
+        slug: /reference/models/recordstatus/ready
+      orchard.pagination:
+        documentId: reference.pagination
+        slug: /reference/pagination
+      orchard.pagination.Page:
+        documentId: reference.pagination.Page
+        slug: /reference/pagination/page
+      orchard.pagination.Page.has_more:
+        documentId: reference.pagination.Page.has_more
+        slug: /reference/pagination/page/has-more
+      orchard.pagination.Page.items:
+        documentId: reference.pagination.Page.items
+        slug: /reference/pagination/page/items
+      orchard.pagination.Page.map:
+        documentId: reference.pagination.Page.map
+        slug: /reference/pagination/page/map
+      orchard.pagination.Page.next_cursor:
+        documentId: reference.pagination.Page.next_cursor
+        slug: /reference/pagination/page/next-cursor
+      orchard.pagination.Page.total:
+        documentId: reference.pagination.Page.total
+        slug: /reference/pagination/page/total
+      orchard.pagination.T:
+        documentId: reference.pagination.T
+        slug: /reference/pagination/t
+      orchard.pagination.U:
+        documentId: reference.pagination.U
+        slug: /reference/pagination/u
+    layout: classes
+    singlePage:
+      documentId: reference.complete
+      slug: /reference/all
+      title: Complete Python SDK reference
+      summary: Browse every public module, class, method, and field on one page.
+navigation:
+  - id: start
+    doc: guide.start
+  - id: complete
+    doc: reference.complete
+  - id: overview
+    label: Package
+    items:
+      - id: orchard
+        doc: reference.orchard
+      - id: orchard.client
+        doc: reference.clients
+  - id: client
+    label: Synchronous client
+    items:
+      - id: orchard.client.Client
+        doc: reference.client
+      - id: orchard.client.Client.__init__
+        doc: reference.Client.__init__
+      - id: orchard.client.Client.fetch
+        doc: reference.fetch
+      - id: orchard.client.Client.list_records
+        doc: reference.Client.list_records
+      - id: orchard.client.Client.iter_records
+        doc: reference.Client.iter_records
+      - id: orchard.client.Client.create_record
+        doc: reference.Client.create_record
+      - id: orchard.client.Client.bulk_create
+        doc: reference.Client.bulk_create
+  - id: async
+    label: Asynchronous client
+    items:
+      - id: orchard.client.AsyncClient
+        doc: reference.AsyncClient
+      - id: orchard.client.AsyncClient.fetch
+        doc: reference.AsyncClient.fetch
+      - id: orchard.client.AsyncClient.iter_records
+        doc: reference.AsyncClient.iter_records
+  - id: models
+    label: Models
+    items:
+      - id: orchard.models
+        doc: reference.models
+      - id: orchard.models.Record
+        doc: reference.models.Record
+      - id: orchard.models.RecordInput
+        doc: reference.models.RecordInput
+      - id: orchard.models.RecordDict
+        doc: reference.models.RecordDict
+      - id: orchard.models.RecordStatus
+        doc: reference.models.RecordStatus
+      - id: orchard.models.Record.to_dict
+        doc: reference.models.Record.to_dict
+  - id: pagination
+    label: Pagination
+    items:
+      - id: orchard.pagination.Page
+        doc: reference.pagination.Page
+      - id: orchard.pagination.Page.map
+        doc: reference.pagination.Page.map
+      - id: orchard.pagination.Page.has_more
+        doc: reference.pagination.Page.has_more
+  - id: errors
+    label: Exceptions
+    items:
+      - id: orchard.errors
+        doc: reference.errors
+      - id: orchard.errors.APIError
+        doc: reference.errors.APIError
+      - id: orchard.errors.AuthenticationError
+        doc: reference.errors.AuthenticationError
+      - id: orchard.errors.NotFoundError
+        doc: reference.errors.NotFoundError
+      - id: orchard.errors.RateLimitError
+        doc: reference.errors.RateLimitError

package/examples/code-references/python/orchard/__init__.py

@@ -0,0 +1,11 @@
+"""A sample SDK for working with records, collections, and paginated results.
+
+Use [Client](symbol:orchard.client.Client) in synchronous applications, or
+[AsyncClient](symbol:orchard.client.AsyncClient) in an async service. Models,
+pagination helpers, and typed exceptions have their own reference pages.
+
+This package is documentation example code. It doesn't contact a live service.
+"""
+from .client import AsyncClient, Client
+from .models import Record, RecordInput, RecordStatus
+from .pagination import Page

package/examples/code-references/python/orchard/client.py

@@ -0,0 +1,212 @@
+"""Synchronous and asynchronous clients for the sample records SDK."""
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Literal, overload
+from .errors import AuthenticationError, NotFoundError
+from .models import Record, RecordDict, RecordInput, RecordStatus
+from .pagination import Page
+
+class Client:
+    """Manage records from a synchronous Python application.
+
+    Create one client per API credential and reuse it across requests. Use
+    [AsyncClient](symbol:orchard.client.AsyncClient) in an async application.
+
+    The sample client keeps records in memory; it doesn't make network calls.
+    """
+    def __init__(self, api_key: str, *, base_url: str = "https://api.example.com/v1", timeout: float = 10.0, max_retries: int = 2):
+        """Configure a reusable client.
+
+        Args:
+            api_key: Credential used to identify the application.
+            base_url: Root URL of the API deployment.
+            timeout: Default request timeout, in seconds.
+            max_retries: Number of retries for transient failures.
+
+        Raises:
+            AuthenticationError: If the API key is empty.
+        """
+        if not api_key:
+            raise AuthenticationError("API key must not be empty")
+        self.base_url = base_url
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._records: dict[str, Record] = {"rec_42": Record("rec_42", "Getting started")}
+
+    @overload
+    def fetch(self, record_id: str, *, raw: Literal[False] = False, timeout: float | None = None) -> Record: ...
+    @overload
+    def fetch(self, record_id: str, *, raw: Literal[True], timeout: float | None = None) -> RecordDict: ...
+    def fetch(self, record_id: str, *, raw: bool = False, timeout: float | None = None) -> Record | RecordDict:
+        """Retrieve a record by its stable identifier.
+
+        The default response is a typed [Record](symbol:orchard.models.Record).
+        Set `raw=True` to receive a dictionary for serialization or a legacy
+        integration. An explicit timeout overrides the client's default.
+
+        Args:
+            record_id: Stable identifier of the record to retrieve.
+            raw: Return a wire-format dictionary instead of a model.
+            timeout: Request timeout override, in seconds.
+
+        Returns:
+            The record model, or a dictionary when `raw=True`.
+
+        Raises:
+            ValueError: If the record identifier is empty.
+            NotFoundError: If no record matches the identifier.
+
+        Examples:
+            >>> client = Client("demo-key")
+            >>> record = client.fetch("rec_42")
+            >>> record.title
+            'Getting started'
+            >>> payload = client.fetch("rec_42", raw=True)
+            >>> payload["status"]
+            'ready'
+        """
+        if not record_id:
+            raise ValueError("record_id must not be empty")
+        if record_id not in self._records:
+            raise NotFoundError(f"Record {record_id} was not found")
+        record = self._records[record_id]
+        return record.to_dict() if raw else record
+
+    def list_records(self, *, limit: int = 20, cursor: str | None = None, status: RecordStatus | None = None) -> Page[Record]:
+        """List a single page of records with optional status filtering.
+
+        Use [iter_records](symbol:orchard.client.Client.iter_records) when you
+        want to read every page without managing continuation cursors.
+
+        Args:
+            limit: Maximum number of records in a page, from 1 to 100.
+            cursor: Opaque continuation token from an earlier response.
+            status: Include only records with this processing status.
+
+        Returns:
+            A page of matching records with an optional continuation cursor.
+
+        Raises:
+            ValueError: If the page size is outside the supported range.
+
+        Examples:
+            >>> page = client.list_records(limit=10, status=RecordStatus.READY)
+            >>> titles = page.map(lambda record: record.title)
+        """
+        if not 1 <= limit <= 100:
+            raise ValueError("limit must be between 1 and 100")
+        records = [r for r in self._records.values() if status is None or r.status == status]
+        start = int(cursor or "0")
+        end = start + limit
+        return Page(records[start:end], str(end) if end < len(records) else None, len(records))
+
+    def iter_records(self, *, page_size: int = 20, status: RecordStatus | None = None) -> Iterator[Record]:
+        """Iterate through records across every page.
+
+        Pagination is lazy: another page is read only when the iterator needs it.
+        Stop iteration early to avoid fetching pages your application won't use.
+
+        Args:
+            page_size: Number of records requested per page, from 1 to 100.
+            status: Optional processing status filter.
+
+        Yields:
+            Records in the service's response order.
+
+        Examples:
+            >>> for record in client.iter_records(page_size=50):
+            ...     print(record.id, record.title)
+        """
+        cursor = None
+        while True:
+            page = self.list_records(limit=page_size, cursor=cursor, status=status)
+            yield from page.items
+            if not page.has_more:
+                return
+            cursor = page.next_cursor
+
+    def create_record(self, data: RecordInput, *, idempotency_key: str | None = None) -> Record:
+        """Create a record from a typed input model.
+
+        Use an idempotency key when retrying a request after a timeout. Reuse the
+        same key only for retries of the same logical operation.
+
+        Args:
+            data: Title and labels for the new record.
+            idempotency_key: Application-generated retry token.
+
+        Returns:
+            An immutable snapshot of the created record.
+
+        Examples:
+            >>> data = RecordInput(title="Deployment notes", labels={"team": "platform"})
+            >>> record = client.create_record(data, idempotency_key="deploy-42")
+        """
+        record = Record(f"rec_{len(self._records) + 1}", data.title, labels=data.labels)
+        self._records[record.id] = record
+        return record
+
+    def bulk_create(self, records: Sequence[RecordInput], *, batch_size: int = 25) -> list[Record]:
+        """Create multiple records in bounded batches.
+
+        Args:
+            records: Input models to create, in submission order.
+            batch_size: Maximum number of records per batch, from 1 to 100.
+
+        Returns:
+            Created records in the same order as the submitted inputs.
+
+        Raises:
+            ValueError: If the batch size is outside the supported range.
+        """
+        if not 1 <= batch_size <= 100:
+            raise ValueError("batch_size must be between 1 and 100")
+        return [self.create_record(item) for item in records]
+
+class AsyncClient:
+    """Use the records SDK from an async Python application.
+
+    Await individual operations, or use `async for` to consume a record iterator.
+    This example delegates to an in-memory client; no network calls are made.
+    """
+    def __init__(self, api_key: str, *, timeout: float = 10.0):
+        """Configure an async client.
+
+        Args:
+            api_key: Application credential.
+            timeout: Default request timeout, in seconds.
+        """
+        self._client = Client(api_key, timeout=timeout)
+
+    async def fetch(self, record_id: str, *, timeout: float | None = None) -> Record:
+        """Await a typed record response.
+
+        Args:
+            record_id: Stable record identifier.
+            timeout: Optional request timeout override, in seconds.
+
+        Returns:
+            The matching record model.
+
+        Raises:
+            NotFoundError: If the record doesn't exist.
+
+        Examples:
+            >>> record = await client.fetch("rec_42")
+        """
+        return self._client.fetch(record_id, timeout=timeout)
+
+    async def iter_records(self, *, page_size: int = 20) -> AsyncIterator[Record]:
+        """Consume paginated records using asynchronous iteration.
+
+        Args:
+            page_size: Maximum number of records read in one page.
+
+        Yields:
+            Typed records from successive pages.
+
+        Examples:
+            >>> async for record in client.iter_records(page_size=50):
+            ...     print(record.title)
+        """
+        for record in self._client.iter_records(page_size=page_size):
+            yield record