An opinionated documentation generator for Effect projects.

This library was inspired by the following projects:

• docs-ts

1. Install @effect/docgen as a dev dependency:

pnpm add @effect/docgen -D

2. (Optional) Add a docgen.json configuration file.

{
  "$schema": "node_modules/@effect/docgen/schema.json"
}

3. Add the following script to your package.json file:

{
  "scripts": {
    "docgen": "docgen"
  }
}

The docgen.json configuration file allows you to customize docgen's behavior. Here's an example configuration:

{
  "exclude": ["src/internal/**/*.ts"],
  "parseCompilerOptions": {
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "moduleResolution": "Bundler",
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "paths": {
      "@effect/<project-name>": ["./src/index.js"],
      "@effect/<project-name>/test/*": ["./test/*.js"],
      "@effect/<project-name>/examples/*": ["./examples/*.js"],
      "@effect/<project-name>/*": ["./src/*.js"]
    }
  },
  "examplesCompilerOptions": {
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "moduleResolution": "Bundler",
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "paths": {
      "@effect/<project-name>": ["../../src/index.js"],
      "@effect/<project-name>/test/*": ["../../test/*.js"],
      "@effect/<project-name>/examples/*": ["../../examples/*.js"],
      "@effect/<project-name>/*": ["../../src/*.js"]
    }
  }
}

By default, docgen will search for files in the src directory and will output generated files into a docs directory. For information on how to configure docgen, see the Configuration section below.

docgen is meant to be a zero-configuration command-line tool by default. However, there are several configuration settings that can be specified for docgen. To customize the configuration of docgen, create a docgen.json file in the root directory of your project and indicate the custom configuration parameters that the tool should use when generating documentation.

The docgen.json configuration file adheres to the following interface:

interface Config {
  readonly projectHomepage?: string;
  readonly srcDir?: string;
  readonly outDir?: string;
  readonly theme?: string;
  readonly enableSearch?: boolean;
  readonly enforceDescriptions?: boolean;
  readonly enforceExamples?: boolean;
  readonly enforceVersion?: boolean;
  readonly exclude?: ReadonlyArray<string>;
  readonly parseCompilerOptions?: string | Record<string, unknown>;
  readonly examplesCompilerOptions?: string | Record<string, unknown>;
}

The following table describes each configuration parameter, its purpose, and its default value.

Q: For functions that have overloaded definitions, is it possible to document each overload separately?

A: No, docgen will use the documentation provided for the first overload of a function in its generated output.

The MIT License (MIT)