Generate code API references

A code API reference describes a library's classes, functions, methods, fields, parameters, return values, and exceptions. A guide explains how to accomplish a task; the reference explains what a programmer can call, what to pass, and what comes back. OpenAPI references describe HTTP endpoints instead.

Shoalrun reads a converter's JSON snapshot and renders native reference pages. The optional Python adapter extracts local source and docstrings with Griffe. Other languages can supply a converter that writes the same snapshot format. A Kotlin-shaped snapshot is supported; a Kotlin extractor isn't bundled.

Before you start

Use an existing documentation project with @shoalrun/cli installed, as in Getting started. Run the commands below from that project's directory. Extraction needs Python 3.11 or newer and an explicit dependency installation. Normal site builds read the snapshot and don't need Python.

The adapter doesn't import the documented package, execute its code, enable Griffe extensions, or inspect installed modules. Review public source declarations and docstrings before publishing: static extraction doesn't establish that their content is safe to disclose.

Add Python source

Create src/sample.py. This fictional example returns a local dictionary and doesn't contact a service:

class Client:
    """Retrieve records for an application."""

    def fetch(self, record_id: str) -> dict[str, str]:
        """Retrieve a record by its stable identifier.

        Args:
            record_id: Identifier of the record to retrieve.

        Returns:
            A mapping containing the record identifier.
        """
        return {"id": record_id}

Keep the source root limited to the package you're documenting. The adapter rejects symlinks inside that root, including links to files outside it.

Extract and validate a snapshot

Create an isolated Python environment and install the adapter's pinned requirements:

python3.11 -m venv .venv-reference
.venv-reference/bin/python -m pip install --require-hashes \
  -r node_modules/@shoalrun/cli/adapters/python/requirements.txt
mkdir -p reference
.venv-reference/bin/python node_modules/@shoalrun/cli/adapters/python/shoalrun_reference.py \
  --root ./src --module sample --style google --out ./reference/python.json
npx --no-install shoalrun references check ./reference/python.json

Use --style google, numpy, or sphinx to match the docstring convention. The adapter preserves signatures, supported docstring sections, local source locations, and resolved local type references. It skips aliases and underscore-prefixed members except constructors. It doesn't expand inherited members, execute decorators, or resolve external re-exports. Review the JSON before building.

The check reports status: "ok", the programming language, and the symbol count. Duplicate IDs, missing referenced symbols, cyclic ownership, and invalid fields fail validation. A missing Python dependency stops extraction; Shoalrun doesn't install it during a site build.

Register the catalog and navigation

Add these settings to docs.config.yaml, retaining the project's existing site and publication settings:

codeReferences:
  sdk:
    source: { kind: file, path: ./reference/python.json }
    layout: classes
    singlePage:
      documentId: reference.sdk.complete
      slug: /reference/sdk/all
      title: Complete SDK reference
    symbols:
      sample.Client:
        documentId: reference.sdk.client
        slug: /reference/sdk/client
navigation:
  - { id: sdk-client, doc: reference.sdk.client }
  - { id: sdk-complete, doc: reference.sdk.complete }

If navigation already exists, append those entries to the appropriate group. References use ordinary doc: entries. Explicit document IDs and slugs preserve intentional public identities. Generated defaults follow the catalog and symbol IDs. Renaming a source symbol changes its default identity.

Choose the reading layout

Use layout to control how much detail readers see on a parent page. Individual symbol URLs stay available in every layout. Group the class or module pages in navigation when you want fewer menu entries.

singlePage independently adds a complete reference for the catalog. It works with any layout. Omit it or set singlePage: false to disable it. In a grouped or complete page, links to included symbols jump to their sections; other links retain individual symbol URLs. See the configuration reference for defaults and metadata options.

Build and verify

Build the site, then serve the same output:

npx --no-install shoalrun build docs.config.yaml site-dist
npx --no-install shoalrun serve site-dist --port 8770

Open http://127.0.0.1:8770/reference/sdk/client/ and /reference/sdk/all/. The class page should include fetch details. The complete page should include the module, class, and method. Read their Markdown copies at /reference/sdk/client.md and /reference/sdk/all.md and verify that signatures, parameter descriptions, and return information remain readable.

Regenerate the snapshot after changing source or docstrings, then validate and rebuild. A site build doesn't rerun the converter. The packaged examples/code-references project has a larger sample SDK with models, async methods, overloads, pagination, and exceptions.

Versions, profiles, and delivery

Bind different snapshots to explicit product/channel/version/language publications when releases have different interfaces. programmingLanguage: python describes the source language; publication language: en describes the documentation language.

Catalog and per-symbol metadata can declare reader filters, shared, and requires. Use the same profile for build and export. Grouped and complete pages include only symbols eligible in their publication and build selection; they don't grant access to excluded symbols. See Publications, Customer editions, and the reference for the configuration.

HTML, Markdown, and agents

HTML uses compact declaration blocks, linked types, field/default tables, and symbol sections. Tables scroll horizontally on narrow screens and can receive keyboard focus. Copy controls use JavaScript; reading the reference, following symbol links, and scrolling a table don't require it. A full reference is an ordinary generated page, so browser Find can search its content.

Markdown retains declarations, descriptions, tables, examples, and symbol links. It doesn't include Copy controls or the website styling. Content exports preserve typed resource links and scope; PDF workflows can select a grouped page or the complete reference by document ID. Generated symbol pages remain independently addressable even when they're also shown inline elsewhere.

Agents can discover and read the generated pages through the site's indexes and read-only tools, or use the normal content-delivery API. They don't need Python or browser scripts to read published references. Source extraction describes declared interfaces; it doesn't execute examples or prove runtime behavior.

Related reading

Reference while working

• Add an OpenAPI API — Generate HTTP endpoint references when an OpenAPI contract describes the interface.
• Code API reference settings — Check catalog settings, snapshot fields, and converter limits.