Skip to Content
⚠️Active Development Notice: TimeTiles is under active development. Information may be placeholder content or not up-to-date.
Developer GuideDevelopment SetupDocumentation Guide

Documentation Guide

This guide explains how documentation works in the TimeTiles project, including both manual documentation and auto-generated API references.

Documentation Structure

The TimeTiles documentation is divided into two main categories:

1. Manual Documentation

Location: Various directories under /apps/docs/content/

  • Getting Started (/getting-started/) - Installation, quick start guides
  • User Guide (/user-guide/) - Features, use cases, tutorials
  • Developer Guide (/developer-guide/) - Architecture, development guides
  • Admin Guide (/admin-guide/) - Deployment, configuration, maintenance

These are hand-written MDX files that you edit directly.

2. Auto-generated API Documentation

Location: /apps/docs/content/reference/api/

  • Generated from JSDoc comments in source code
  • Created using TypeDoc with post-processing
  • Should NOT be edited manually (changes will be overwritten)

Working with Manual Documentation

Creating New Pages

  1. Create an .mdx file in the appropriate directory:
apps/docs/content/developer-guide/guides/my-new-guide.mdx
  1. Write your content using MDX (Markdown + JSX):
# My Guide Title
 
import { Callout } from "nextra/components";
 
<Callout type="info">Important information here</Callout>
 
## Section with code
 
\`\`\`typescript
const example = "code here"
\`\`\`
  1. Update the navigation by editing _meta.json in the same directory:
{
  "existing-page": "Existing Page",
  "my-new-guide": "My New Guide"
}

Best Practices for Manual Docs

  • Use clear, descriptive titles
  • Include practical examples
  • Add screenshots where helpful
  • Link to related documentation
  • Keep content up-to-date with code changes

Working with Auto-generated API Documentation

How It Works

  1. Source: JSDoc comments in TypeScript files
    • Located in apps/web/lib/, apps/web/app/api/
  2. Generation: TypeDoc processes JSDoc comments
    • Configuration in apps/web/typedoc.json
  3. Output: Markdown files in apps/docs/content/reference/api/
    • Automatically organized by module
  4. Post-processing: Script cleans and converts output
    • Converts .md to .mdx
    • Generates navigation files

Writing JSDoc Comments

Currently, we primarily use file-level documentation to describe modules:

/**
 * Handles import job processing with support for CSV and Excel files.
 *
 * This module manages the complete import pipeline including
 * file parsing, schema detection, validation, geocoding, and event creation.
 *
 * @module
 * @category Services
 */

Key tags we use:

  • @module - Marks file-level documentation
  • @category - Groups related modules (Services, Collections, Jobs, etc.)

Generating API Documentation

One-time Generation

# From project root
pnpm docs:api
 
# Or from docs directory
cd apps/docs
pnpm docs:api

Watch Mode (Development)

For active development on API documentation:

# From docs directory
cd apps/docs
pnpm docs:api:watch

This watches apps/web/lib/ for changes and automatically regenerates documentation.

What Gets Generated

The TypeDoc configuration (apps/web/typedoc.json) specifies:

  • Entry points: lib/collections, lib/services, lib/jobs, app/api, etc.
  • Output location: apps/docs/content/reference/api/
  • Exclusions: Test files, internal functions
  • Organization: Grouped by category

Processing Steps

The pnpm docs:api command:

  1. Runs TypeDoc to generate markdown files
  2. Converts .md files to .mdx (via clean-typedoc-output.ts)
  3. Cleans up problematic references
  4. Navigation is derived from the file structure (Nextra auto-indexes without _meta.json)

Git Configuration

What’s Tracked vs Ignored

The .gitignore excludes all generated API documentation:

apps/docs/content/reference/api/**/*.md
apps/docs/content/reference/api/**/*.mdx
apps/docs/content/reference/api/**/_meta.json
!apps/docs/content/reference/api/index.mdx

Everything in the API reference directory is regenerated from source code on each build.

This means:

  • ✅ Generated docs don’t clutter git history
  • ✅ Can regenerate anytime from source
  • ✅ Navigation is derived from file structure (Nextra auto-indexes directories)
  • ✅ Consistent with source code structure

Note: The top-level content/reference/_meta.json IS manually maintained and tracked in git.

Development Workflow

When Adding New Features

  1. Write the code with comprehensive JSDoc comments
  2. Run tests to ensure everything works
  3. Generate docs with pnpm docs:api
  4. Write guides if needed (manual documentation)
  5. Review the generated documentation
  6. Commit code changes (docs are regenerated in CI)

When Updating Documentation

For API Changes:

  1. Update JSDoc comments in source files
  2. Run pnpm docs:api to regenerate
  3. Verify the output looks correct
  4. Commit the source code changes

For Guides/Tutorials:

  1. Edit the .mdx files directly
  2. Preview with pnpm dev
  3. Commit the documentation changes

CI/CD Integration

The documentation build process:

  1. Development: Docs generated on-demand
  2. Pull Requests: Docs built to verify they compile
  3. Production: Docs generated fresh during build

Build command:

{
  "build": "pnpm docs:api && next build"
}

This ensures documentation is always up-to-date with the code.

Troubleshooting

Common Issues

Generated docs look wrong

  • Check JSDoc syntax in source files
  • Verify TypeDoc configuration
  • Run pnpm docs:api with clean output directory
  • Edit the appropriate _meta.json file
  • These are NOT auto-generated
  • Use relative paths for internal links
  • Verify file exists after generation
  • Check for typos in paths

TypeDoc warnings

  • Missing type exports: Export the type from index
  • Unresolved references: Ensure proper imports
  • Private members documented: Add @internal tag

Debugging Commands

# Clean generated docs
rm -rf apps/docs/content/reference/api/lib
rm -rf apps/docs/content/reference/api/app
 
# Regenerate fresh
cd apps/docs && pnpm docs:api
 
# Check what's ignored by git
git check-ignore apps/docs/content/reference/api/**
 
# See TypeDoc configuration
cat apps/web/typedoc.json

Best Practices

For Module Documentation

  1. Clear purpose: Describe what the module does
  2. Keep updated: Update when functionality changes
  3. Use categories: Group related modules together

For Manual Documentation

  1. User-focused: Write for your audience
  2. Practical examples: Show real-world usage
  3. Visual aids: Include diagrams/screenshots where helpful
  4. Cross-reference: Link to related guides
  5. Keep concise: Avoid unnecessary verbosity

Documentation Review Checklist

  • Module-level JSDoc comments added for new files
  • Manual guides updated if behavior changed
  • Navigation (_meta.json) updated if needed
  • Links verified and working
  • Generated docs reviewed for accuracy

Resources

Last updated on
Development SetupTesting Guidelines