@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/example-configs/facet-sections/README.md

@@ -0,0 +1,37 @@
+# Additional information in a selected build
+
+This example uses one shared page, with an internal operations section. It needs
+no customer profile or feature manifest. From this directory, with Shoalrun installed:
+
+```sh
+shoalrun build docs.config.yaml dist/complete
+shoalrun build customer.config.yaml dist/customer
+shoalrun serve dist/complete --port 8771
+```
+
+Open <http://127.0.0.1:8771/>. In another terminal, serve the customer output:
+
+```sh
+shoalrun serve dist/customer --port 8772
+```
+
+Open <http://127.0.0.1:8772/>. Both sites show **Review a bill** and **Get help**.
+Only the complete build has **Check the retry queue**. Check `index.md` and
+`search-index.json` in each output: the customer files must contain neither that
+heading nor its instructions. The unfiltered build includes all valid blocks.
+
+**Unmarked sections stay included. Unmarked pages are excluded when a selected
+facet has no matching page mark.** This page explicitly belongs to both audiences.
+`<ForFacet audience="internal partner">` would accept either choice if both were
+configured; multiple facet attributes must all match. A facet the build doesn't
+filter passes automatically. Selection removes sections rather than swapping
+variants. Use positive literal matches only.
+
+`<ReaderSection>` is different: it hides content in browser views while publishing
+it in output files. Never use it to omit internal instructions from a customer
+build. Build-time omission doesn't authenticate the complete site's deployment.
+
+After each successful build, `.shoalrun/content-selection.json` records its target
+and section decisions. Follow its `receipt` path for the artifact-specific copy;
+these reports belong outside served output. Portable exports need their own
+`contentFilter`; PDF exports inherit the site's filter unless overridden.

package/example-configs/facet-sections/base.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+site:
+  title: Service documentation
+  contentDir: content
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { customer: Customers, internal: Internal }
+outputs:
+  html:
+    shareImages: false
+    highlighting: { provider: none }
+navigation:
+  - { id: billing, doc: guide.billing }

package/example-configs/facet-sections/content/billing.mdx

@@ -0,0 +1,25 @@
+---
+id: guide.billing
+title: Billing
+summary: Understand billing and check operational status.
+slug: /
+audiences: [customer, internal]
+---
+
+## Review a bill
+
+Open the billing page and choose the billing period. Check the total and download
+the statement before contacting support about a charge.
+
+<ForFacet audience="internal">
+
+## Check the retry queue
+
+Before replaying a failed billing job, check whether the original request
+completed. Record the job identifier and use the team's approved replay procedure.
+
+</ForFacet>
+
+## Get help
+
+Include the statement identifier and billing period in your support request.

package/example-configs/facet-sections/customer.config.yaml

@@ -0,0 +1,4 @@
+extends: [./base.yaml]
+site:
+  title: Customer documentation
+  contentFilter: { audience: [customer] }

package/example-configs/facet-sections/docs.config.yaml

@@ -0,0 +1,3 @@
+extends: [./base.yaml]
+site:
+  title: Complete documentation

package/example-configs/faceted-sites/README.md

@@ -19,8 +19,10 @@ all applicable values, or supply appropriate `readerFilters.typeDefaults`.
 Unknown facets, unknown choices, empty selectors, and selections with no pages
 fail the build. Omit `contentFilter` to publish all otherwise eligible pages.
 
-Selection applies to whole authored and generated pages before rendering. A
-selected page retains its complete body, including reader-marked sections.
+Selection applies to authored and generated pages before rendering. On a selected
+page, `<ForFacet>` blocks also follow the build selection. Unmarked sections stay
+included, and `<ReaderSection>` content remains published. See
+[the audience section example](../facet-sections/README.md).
 Reader controls do not bring excluded pages back. Keep links and navigation
 within the selected set; missing targets fail validation. Configure API sources
 and operation selection separately: publishing an API contract may expose the

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