@fp-tx/documenter

documenter

Documenter is a lightweight markdown file generator for fp-tx libraries similar to docs-ts which creates markdown files by parsing the .api.json file generated by @microsoft/api-extractor.

Disclaimer

Documenter is limited currently to creating files for each namespace export from a single entrypoint. Support for differing library schemes will be explored in the future.

Supported TSDoc Tags

Tag Name	Tag Type	Example	Parent Tag	Notes
@remarks	Native block tag
@deprecated	Native block tag
@example	Native block tag			Requires code fences and language specifier
@public	Native modifier tag			Also: @beta and @alpha
@meta	Custom block tag	@meta		A block tag which is used to group the custom tags used by documenter
@since	Custom inline tag	{@since 0.1.0}	@meta	Used to indicate when this export was added
@category	Custom inline tag`	{@category Models}	@meta	Used to group similar exports
@deprecationSchedule	Custom inline tag	{@deprecationSchedule 0.2.0}	@meta	Used to indicate the version in which this export will be deprecated
@removalSchedule	Custom inline tag	{@removalSchedule 0.3.0}	@meta	Used to indicate the version in which this export will be removed
@license	Custom inline tag	{@license MIT – Copyright (c) 2024-present Jacob Alford}	@meta	Used to indicate that this export is licensed under a particular copyright

TSDoc Tag Example

/**
 * Fetches a user by their id
 *
 * @remarks
 * This function is deprecated and will be removed in the next major version. Please use
 * `fetchUserById` instead.
 * @deprecated
 * @example
 *
 * ```typescript
 * import * as RTE from 'fp-ts/ReaderTaskEither'
 * import { FetchService, FetchError, User } from './types'
 *
 * const fetchUser123 = fetchUser('123')
 * ```
 *
 * @public
 * @meta
 * {@since 0.1.0}
 * {@category Effects}
 * {@deprecationSchedule 0.2.0}
 * {@removalSchedule 0.3.0}
 * {@license MIT – Copyright (c) 2024-present Jacob Alford}
 */
export declare const fetchUser: (
  userId: string,
) => RTE.ReaderTaskEither<FetchService, FetchError, User>

Installation

Note: Documenter expects prettier as a peer dependency, and is used for formatting type signatures generated by the library.

PNPM

pnpm add -D @fp-tx/documenter

NPM

npm i @fp-tx/documenter --save-dev

Yarn

yarn add -D @fp-tx/documenter

Usage

Documenter can be invoked using npx or by adding a script to your package.json (replacing pnpm with your package manager of choice).

{
  "scripts": {
    "docs:extract": "api-extractor run --local --verbose",
    "docs:pack": "fp-tx-documenter -i ./temp/mylib.api.json -o ./docs",
    "docs": "pnpm run build && pnpm run docs:extract && pnpm run docs:pack"
  }
}

CLI Options

fp-tx-documenter --help

• -i, --input - The input JSON file generated by @microsoft/api-extractor.
• -o, --output - The output directory for the generated markdown files.