Skip to content

DOCS.md

Latest commit

 

History

History
171 lines (118 loc) · 4.97 KB

DOCS.md

File metadata and controls

171 lines (118 loc) · 4.97 KB

Plot Twist Creator Documentation

This directory contains the TypeDoc-generated API documentation for the Plot Twist Creator.

Published Documentation

The Twist Creator documentation is automatically published to GitHub Pages whenever changes are pushed to the main branch:

Live Documentation: https://plotday.github.io/plot/

The documentation is automatically updated whenever changes to the Twist Creator are merged into the main branch, ensuring developers always have access to the latest API reference.

Generating Documentation

The documentation is automatically generated during the build process, but you can also generate it manually.

Generate Documentation

# From the Twist Creator directory
pnpm build:docs

This will create the documentation in dist/docs/

Clean Documentation

# Remove the generated docs
pnpm clean:docs

Viewing Documentation Locally

After generating the documentation, you can view it by opening the generated HTML files in your browser:

# Cross-platform way (recommended)
pnpm docs:open

This script automatically uses the correct command for your platform:

  • open on macOS
  • xdg-open on Linux
  • start on Windows

You can also open it manually:

# macOS
open dist/docs/index.html

# Linux
xdg-open dist/docs/index.html

# Windows
start dist/docs/index.html

Documentation Structure

The generated documentation includes:

  • Classes - Twist, Tool, and built-in tool classes
  • Interfaces - Activity, Priority, Contact, and other data types
  • Enums - ActivityType, ActorType, ActivityLinkType, etc.
  • Type Aliases - NewActivity, NewPriority, and utility types
  • Modules - Organized by functionality (tools, common, utils)

Publishing Documentation

The documentation is automatically published in two ways:

1. GitHub Pages (Automatic)

When changes to the Twist Creator are pushed to the main branch, a GitHub Action automatically:

Workflow Location: .github/workflows/deploy-docs.yml

Trigger: Automatic on push to main when files in public/twist/** change

2. npm Package (Manual)

The documentation is included when the package is built and published to npm. Users can access it by:

  1. Viewing online at GitHub Pages (see above)
  2. Exploring the dist/docs/ directory in the published npm package
  3. Using TypeScript language server features in their IDE for inline documentation

GitHub Pages Setup

If you need to enable or configure GitHub Pages for this repository:

  1. Go to Repository Settings → Pages
  2. Under "Source", select: GitHub Actions
  3. The workflow will automatically handle deployment

The deploy-docs.yml workflow includes all necessary permissions and configurations for GitHub Pages deployment.

Configuration

The documentation generation is configured in typedoc.json. Key settings:

  • Entry Points: Main Twist Creator exports (twist, tool, plot, tools/*)
  • Output: dist/docs/
  • Visibility: Public APIs only (excludes private/protected/internal members)
  • Theme: Default TypeDoc theme optimized for GitHub Pages
  • Source Links: Links to source code on GitHub

Customization

To modify the documentation output:

  1. Edit typedoc.json to change TypeDoc settings
  2. Adjust which files are documented by modifying the entryPoints array
  3. Customize the theme, navigation, or sorting options

See the TypeDoc documentation for more configuration options.

Contributing

When adding new public APIs:

  1. Add comprehensive JSDoc comments to your code
  2. Use @param tags for function parameters
  3. Use @returns tag for return values
  4. Use @example tags to show usage examples
  5. Use @see tags to link to related APIs
  6. Regenerate docs with pnpm build:docs to verify formatting

JSDoc Example

/**
 * Creates a new activity in the current priority.
 *
 * Activities are the core data type in Plot, representing tasks, events, and notes.
 * This method creates a new activity with the specified properties.
 *
 * @param activity - The activity data to create
 * @returns Promise resolving to the created activity with its generated ID
 *
 * @example
 * ```typescript
 * const activity = await this.tools.plot.createActivity({
 *   type: ActivityType.Action,
 *   title: "Review pull request",
 *   links: [{
 *     type: ActivityLinkType.external,
 *     title: "View PR",
 *     url: "https://github.com/org/repo/pull/123"
 *   }]
 * });
 * ```
 *
 * @see {@link Activity} for the full activity type definition
 * @see {@link ActivityType} for available activity types
 */
abstract createActivity(activity: NewActivity): Promise<Activity>;

Support

For issues or questions about the documentation: