Simple Project Examples

OpenDocs examples for single-language libraries

Simple Project Examples

RFC Status: This section contains proposed examples for the OpenDocs Specification RFC.

These examples are provided to illustrate how the specification could be implemented. Provide feedback to help refine these examples.

Simple TypeScript Library

This example demonstrates the most basic OpenDocs implementation for a single-language TypeScript utility library.

Project Structure

opendocs.json Configuration

{
  "documentationSet": {
    "id": "typescript-utils-docs",
    "name": "TypeScript Utilities Documentation",
    "description": "A collection of utility functions for TypeScript",
    "version": "1.0.0",
    "created": "2024-01-15T10:30:00Z"
  },
  "projects": [
    {
      "id": "main",
      "name": "Main Library",
      "language": "typescript",
      "version": "1.2.3",
      "location": {
        "type": "embedded",
        "format": "json"
      }
    }
  ],
  "navigation": {
    "title": "API Reference",
    "groups": [
      {
        "name": "Core API",
        "projects": ["main"]
      }
    ]
  }
}

Generated Documentation

{
  "project": {
    "id": "main",
    "name": "TypeScript Utilities",
    "language": "typescript",
    "items": {
      "format": "json",
      "file": "main-items.json",
      "count": 15
    },
    "metadata": {
      "version": "1.2.3",
      "repository": "https://github.com/example/typescript-utils"
    }
  }
}

Sample DocItems

[
  {
    "id": "math#add",
    "name": "add",
    "kind": "function",
    "language": "typescript",
    "docBlock": {
      "description": "Adds two numbers together",
      "tags": {
        "param": [
          {
            "name": "param",
            "content": "The first number",
            "parameters": { "name": "a", "type": "number" }
          },
          {
            "name": "param",
            "content": "The second number",
            "parameters": { "name": "b", "type": "number" }
          }
        ],
        "returns": ["The sum of a and b"]
      }
    },
    "metadata": {
      "signature": {
        "parameters": [
          { "name": "a", "type": "number" },
          { "name": "b", "type": "number" }
        ],
        "returnType": "number"
      }
    }
  },
  {
    "id": "string#capitalize",
    "name": "capitalize",
    "kind": "function",
    "language": "typescript",
    "docBlock": {
      "description": "Capitalizes the first letter of a string",
      "tags": {
        "param": [
          {
            "name": "param",
            "content": "The string to capitalize",
            "parameters": { "name": "str", "type": "string" }
          }
        ],
        "returns": ["The capitalized string"]
      }
    }
  }
]

Key Takeaways

• Embedded Format: Simple projects can use "type": "embedded" to keep all DocItems in the opendocs.json file
• Minimal Configuration: Only requires basic metadata and project information
• Single Navigation Group: Groups all API items under one navigation section
• JSON Format: Ideal for projects with fewer than 100 documented items

See Also

• Monorepo Examples - Multi-language project examples
• OpenDocs File Organization - Learn about file storage options
• Examples Overview - Back to all examples

---

This example is part of the OpenDocs Specification RFC. Provide feedback to help improve it.