Codocma

Solana Program Docs, Generated by Codama

This package provides a Solana program documentation renderer for Codama that generates markdown or JSON documentation from Solana program IDL files.

This tool is in beta so please report any issues or feedback.

Documentation is generated from the IDL, so for best results it's important to document your Shank Macros well (or add visitors to your renderDocsVisitor (see example below)).

Installation

# Beta version
pnpm add codocma@beta

Usage

Basic Usage

import { renderDocsVisitor } from 'codocma';
import { rootNode } from '@codama/nodes';
import { visit } from '@codama/visitors-core';

// Create or load your Codama root node
const root = rootNode(/* ... */);

// Generate documentation
visit(root, renderDocsVisitor('./docs'));

For more examples of integration with Codama, check out the Codama GitHub repository.

Example Output

• Raydium Program
• Raydium Program JSON

Configuration Options

The renderer accepts various options to customize the output:

visit(
    root,
    renderDocsVisitor('./docs', {
        // Output format: 'markdown' (default) or 'json'
        format: 'markdown',

        // Sections to include: 'instructions', 'accounts', 'types', 'errors', 'pdas'
        sections: ['instructions', 'accounts', 'types', 'errors', 'pdas'],

        // Custom program ID (defaults to the publicKey in IDL)
        programId: 'MyProgram11111111111111111111111111111111111',

        // Include table of contents
        includeTableOfContents: true,

        // Include discriminator values
        includeDiscriminators: true,

        // Delete existing docs folder before generating
        deleteFolderBeforeRendering: false,

        // Custom descriptions for various components
        customDescriptions: {
            instructions: {
                initialize: 'Initialize the program state',
                transfer: 'Transfer tokens between accounts',
            },
            accounts: {
                userAccount: 'Stores user information and settings',
                vaultAccount: 'Holds program funds',
            },
            types: {
                UserRole: 'Defines the role of a user in the system',
            },
            errors: {
                InsufficientFunds: 'Thrown when an account has insufficient funds for the operation',
            },
            pdas: {
                vaultPda: 'The program-derived address for the vault',
            },
        },
    }),
);

Output Format

The renderer generates comprehensive documentation including:

1. Program Overview - Program ID and general information
2. Instructions - All program instructions with:
   • Description
   • Discriminator values
   • Parameters (arguments) with detailed type information
   • Required accounts with their permissions (signer/writable status)
3. Accounts - All program accounts with:
   • Description
   • Discriminator values
   • Field definitions with nested type resolution
   • Link to PDA derivation if available
4. Types - Custom types defined in the program:
   • Enums with:
     • Variant names and descriptions
     • Discriminator values for each variant
     • Fields for struct and tuple variants
     • Size information
   • Structs with:
     • Field names, types, and descriptions
     • Support for complex nested types
   • Support for many Codama type nodes including (e.g., arrays, options, maps, etc.)
5. Errors - Program errors with codes and descriptions
6. PDAs - Program Derived Addresses with:
   • Description
   • Seeds configuration
   • Associated program ID

JSON Output

When using format: 'json', the renderer outputs a structured JSON file:

{
  "programName": "My Program",
  "programId": "MyProgram11111111111111111111111111111111111",
  "instructions": [...],
  "accounts": [...],
  "types": [...],
  "errors": [...],
  "pdas": [...]
}

This format is useful for generating documentation websites or integrating with other tools.

Architecture

Fragments (src/fragments/):

• Template system - Reusable, configurable UI components
• Rendering logic - How to format specific pieces (headers, tables, etc.)
• Presentation layer - Controls styling, layout, formatting

Collectors (src/collectors/):

• Data extraction - Parse AST nodes into structured data
• Business logic - Handle discriminators, descriptions, field extraction
• Data transformation - Convert Codama nodes → TypeScript interfaces

Generators (src/generators/):

• Orchestration - Coordinate fragments to build complete sections
• Content assembly - Combine multiple fragments into cohesive output
• High-level layout - Organize sections, TOC, overall document structure

Data flow:

Codama AST Nodes → Collectors → Structured Data → Generators (using Fragments) → Final Output

Contributing

Submit an issue or PR.