Typedoc Documentation Guide

TypeDoc Documentation Guide

This guide explains how to set up, generate, and maintain API documentation for your project using TypeDoc. It includes configuration options, best practices, and troubleshooting tips.

---

Overview

TypeDoc is a documentation generator for TypeScript projects. It extracts API information from your code and produces a static HTML site. With plugins like typedoc-plugin-vue, TypeDoc can also handle Vue Single File Components (SFCs).

Important Note on Function Documentation

Each function in this project is documented using TSDoc comments within its respective file. Developers should refer directly to the relevant TypeScript files for function details:

• API-related functions → store/geoserver.ts, store/participation.ts
• Filtering functions → components/Map/Layer/Filter/AttributeFiltering.vue, GeometryFiltering.vue
• State management functions → store/map.ts, store/filter.ts

For a complete breakdown of function parameters and usage, refer to the respective files.

---

Prerequisites

• Your project is written in TypeScript.
• If you use Vue SFCs, install typedoc-plugin-vue.
• A valid tsconfig.json that includes your source files (e.g., src/**/*.ts, src/**/*.tsx, src/**/*.vue).

---

Installation

Install TypeDoc and the Vue plugin as development dependencies:

npm install --save-dev typedoc typedoc-plugin-vue

---

Configuration

Create a typedoc.json file in your project root. Below is an example configuration that excludes test files and a specific presets folder:

{
  "entryPoints": ["src"],
  "entryPointStrategy": "expand",
  "out": "docs",
  "exclude": ["**/*.test.ts", "src/presets/**"],
  "tsconfig": "tsconfig.json",
  "plugin": ["typedoc-plugin-vue"],
  "excludeVueProperties": true
}

Explanation of Key Options

• entryPoints: Specifies the starting point for documentation generation. Here, the entire src directory is used.
• entryPointStrategy: Setting this to expand tells TypeDoc to recursively include all files under src that match your tsconfig.json include patterns.
• out: The output directory for the generated documentation (in this case, docs).
• exclude: Patterns for files or directories to exclude (e.g., test files and presets).
• tsconfig: Ensures TypeDoc uses the same TypeScript compiler options as your project.
• plugin: Loads typedoc-plugin-vue to enable processing of Vue SFCs.
• excludeVueProperties: Omits internal Vue properties (e.g., $props, $emit) from the generated documentation.

---

Generating Documentation

Run TypeDoc Locally

Once your configuration is in place, generate the documentation:

npx typedoc

This command uses your typedoc.json settings to generate the documentation in the docs folder.

Adding a Script in package.json

For convenience, add a script so users can generate documentation easily:

{
  "scripts": {
    "docs": "typedoc",
    "dev": "vite",
    "build": "vite build",
    "start": "vite preview"
  }
}

Now, running:

npm run docs

will generate or update the documentation.

---

Best Practices

• Separate Documentation Generation: Keep documentation generation separate (npm run docs) to avoid slowing down development (npm run dev) or production builds (npm run build).
• Automate Updates: Consider integrating documentation generation into your CI/CD pipeline to keep it up to date with code changes.
• Host Your Documentation: Deploy the docs folder to GitHub Pages, Netlify, or Vercel for easy access.
• Use JSDoc/TSDoc Comments: Improve generated docs by adding comments to functions, classes, and exported members.
• Exclude Non-Essential Files: Use exclude in typedoc.json to omit test files and experimental code.

---

Troubleshooting

1. No Entry Points Found

If you receive this warning:

The entry point … is not referenced by the ‘files’ or ‘include’ option in your tsconfig

Ensure your tsconfig.json includes paths for your source files. You may need to adjust your typedoc.json or run TypeDoc with --entryPointStrategy expand.

2. Handling Vue Files

Ensure you have a Vue shims file (src/shims-vue.d.ts) so TypeScript can process .vue files correctly. A typical shims file:

// src/shims-vue.d.ts
declare module "*.vue" {
  import { DefineComponent } from "vue";
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

---

Conclusion

By following this guide, you can efficiently set up and maintain comprehensive API documentation for your TypeScript (and Vue) projects using TypeDoc. Keeping your documentation updated and accessible benefits both developers and users.

Happy documenting! 🚀