0.1.1 • Published 1 month ago
@fp-tx/documenter v0.1.1
documenter
Documenter is a lightweight markdown file generator for fp-tx libraries. Similar to docs-ts, it creates markdown files by traversing the .api.json file generated by @microsoft/api-extractor.
Disclaimer
Documenter is currently limited to creating files for each descendant namespace from a single entrypoint. Support for differing library structures 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 |
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/documenterNPM
npm i @fp-tx/documenter --save-devYarn
yarn add -D @fp-tx/documenterUsage
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.