SDK reference docs

SDK references document class, method signatures, and type interfaces for each SDK. They complement examples in tutorials and guides by providing a comprehensive reference with all the details. They're important for deep understanding of PostHog SDKs and as context for LLM-based tools. Tutorials and guides reference them for parameter and return type details.

Which SDKs have reference docs

It's an ongoing effort to create SDK reference docs for all our SDKs, starting with popular SDKs. Here's the current status:

How the SDK reference docs work

1. SDKs are parsed for basic information like class names, method names, and type interfaces.
2. Descriptions, parameters, return types, and examples are extracted from the SDKs or SDK doc comments.
3. The information is rewritten into a standardized JSON format (HogRef). They're stored in each SDK's repository under a references directory. For example, the JavaScript Web SDK reference is stored here.
4. When an SDK releases a new version, the reference docs are generated automatically. Here's an example workflow.
5. The Strapi instance behind the website is configured to fetch the HogRef JSON files from the SDK's repository and display them on the website via a cron job.
6. The website renders the HogRef JSON files as a table on the SDK reference page.

Each language works slightly differently, but the general process is the same.

Root
├── info (metadata)
├── categories[] (string labels)
├── classes[]
│   ├── functions[]
│   │   ├── params[]
│   │   ├── returnType
│   │   ├── examples[]
│   │   ├── throws[]
│   │   └── overloads[]
│   ├── properties[]
│   ├── staticMethods[]
│   └── events[]
└── types[]
    ├── properties[]
    ├── enumValues[]
    └── generic[]

{
  "id": "example-sdk",
  "schemaVersion": "1.0",
  "info": {
    "id": "example-sdk",
    "title": "Example JavaScript SDK",
    "version": "1.0.0",
    "description": "Example SDK for tracking events.",
    "slugPrefix": "example-sdk",
    "specUrl": "https://github.com/example/example-sdk"
  },
  "categories": ["Capture"],
  "classes": [
    {
      "id": "ExampleClient",
      "title": "ExampleClient",
      "description": "The main client for tracking events.",
      "functions": [
        {
          "id": "capture",
          "title": "capture",
          "description": "Captures an event with optional properties.",
          "details": "You can capture arbitrary object-like values as events.",
          "category": "Capture",
          "releaseTag": "public",
          "showDocs": true,
          "params": [
            {
              "name": "event_name",
              "type": "string",
              "description": "The name of the event (e.g., 'Sign Up', 'Button Click')",
              "isOptional": false
            },
            {
              "name": "properties",
              "type": "Properties | null",
              "description": "Properties to include with the event",
              "isOptional": true
            }
          ],
          "returnType": {
            "id": "CaptureResult | undefined",
            "name": "CaptureResult | undefined"
          },
          "examples": [
            {
              "id": "basic_event_capture",
              "name": "basic event capture",
              "code": "\n\n// basic event capture\nclient.capture('button-clicked', {\n    button_name: 'Get Started',\n    page: 'homepage'\n})\n\n"
            }
          ],
          "path": "lib/src/client.d.ts"
        }
      ]
    }
  ],
  "types": [
    {
      "id": "Properties",
      "name": "Properties",
      "properties": [],
      "path": "lib/src/types.d.ts",
      "example": "{\n    $timestamp: '2024-05-29T17:32:07.202Z',\n    $os: 'Mac OS X',\n    $browser: 'Chrome'\n}"
    }
  ]
}

How to create new SDK reference docs

To contribute a new SDK reference doc:

1. Create a script to parse the SDK's documentation and extract the information into a HogRef JSON file. The script should:
   • Parse for class names, method names, and type interfaces
   • Extract descriptions, parameters, return types, and examples from the SDK or SDK doc comments
   • Format the information according to the HogRef JSON schema specification
   • Store the HogRef JSON file in a references directory in the SDK's repository
   • See existing SDK repositories for examples, such as the JavaScript Web SDK reference
2. Create a workflow to generate the HogRef JSON file when a new version of the SDK is released. See an example workflow.
3. Update the cron-tasks.ts file to fetch the HogRef JSON file from the SDK's repository and display it on the website.
4. Once the HogRef is ingested into the Strapi instance via the cron job, a new page should be created automatically on the website. The website will render the HogRef JSON file as a table on the SDK reference page.
5. Find existing links to the SDK's GitHub repository source code and point them to the new HogRef JSON file instead.