1# @effect/docgen
2
3An opinionated documentation generator for Effect projects.
4
5## Installation
6
7```sh
8npm install -D @effect/docgen
9```
10
11## Links
12
13- [Website](https://effect.website): documentation, guides, and news.
14- [Reference](https://effect.website/docs/v4/api/docgen): API documentation for this package.
15- [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.
16- [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.
17- [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.
18
19## Let's talk
20
21Whether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.
22
23- **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.
24- **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.
25- **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.
26
27## Credits
28
29This library was inspired by the following projects:
30
31- [docs-ts](https://github.com/gcanti/docs-ts)
32
33## Setup
34
351. (Optional) Add a `docgen.json` configuration file.
36
37```json
38{
39 "$schema": "node_modules/@effect/docgen/schema.json"
40}
41```
42
432. Add the following script to your `package.json` file:
44
45```json
46{
47 "scripts": {
48 "docgen": "docgen"
49 }
50}
51```
52
53> [!WARNING]
54> To use "@effect/docgen", Node.js v18 or above is required.
55
56### Example Configuration
57
58The `docgen.json` configuration file allows you to customize `docgen`'s behavior. Here's an example configuration:
59
60```json
61{
62 "exclude": ["src/internal/**/*.ts"],
63 "parseCompilerOptions": {
64 "noEmit": true,
65 "strict": true,
66 "skipLibCheck": true,
67 "moduleResolution": "Bundler",
68 "target": "ES2022",
69 "lib": ["ES2022", "DOM"],
70 "paths": {
71 "@effect/<project-name>": ["./src/index.js"],
72 "@effect/<project-name>/test/*": ["./test/*.js"],
73 "@effect/<project-name>/examples/*": ["./examples/*.js"],
74 "@effect/<project-name>/*": ["./src/*.js"]
75 }
76 },
77 "examplesCompilerOptions": {
78 "noEmit": true,
79 "strict": true,
80 "skipLibCheck": true,
81 "moduleResolution": "Bundler",
82 "target": "ES2022",
83 "lib": ["ES2022", "DOM"],
84 "paths": {
85 "@effect/<project-name>": ["../../src/index.js"],
86 "@effect/<project-name>/test/*": ["../../test/*.js"],
87 "@effect/<project-name>/examples/*": ["../../examples/*.js"],
88 "@effect/<project-name>/*": ["../../src/*.js"]
89 }
90 }
91}
92```
93
94## Supported JSDoc Tags
95
96| Tag | Description | Default |
97| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
98| `@category` | Groups associated module exports together in the generated documentation. | `'utils'` |
99| `@example` | Allows usage examples to be provided for your source code. All examples are type checked using `tsc`. Examples are also run using `tsx` and the NodeJS [assert](https://nodejs.org/api/assert.html) module can be used for on-the-fly testing. | |
100| `@since` | Allows for documenting most recent library version in which a given piece of source code was updated. | |
101| `@deprecated` | Marks source code as deprecated, which will ~~strikethrough~~ the name of the annotated module or function in the generated documentation. | `false` |
102| `@internal` | Prevents `docgen` from generating documentation for the annotated block of code. Additionally, if the `stripInternal` flag is set to `true` in `tsconfig.json`, TypeScript will not emit declarations for the annotated code. | |
103| `@ignore` | Prevents `docgen` from generating documentation for the annotated block of code. | |
104
105By 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](#configuration) section below.
106
107## Configuration
108
109`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.
110
111The `docgen.json` configuration file adheres to the following interface:
112
113```ts
114interface Config {
115 readonly projectHomepage?: string
116 readonly srcLink?: string
117 readonly srcDir?: string
118 readonly outDir?: string
119 readonly theme?: string
120 readonly enableSearch?: boolean
121 readonly enforceDescriptions?: boolean
122 readonly enforceExamples?: boolean
123 readonly enforceVersion?: boolean
124 readonly tscExecutable?: string
125 readonly exclude?: ReadonlyArray<string>
126 readonly parseCompilerOptions?: string | Record<string, unknown>
127 readonly examplesCompilerOptions?: string | Record<string, unknown>
128}
129```
130
131The following table describes each configuration parameter, its purpose, and its default value.
132
133| Parameter | Description | Default Value |
134| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
135| projectHomepage | Will link to the project homepage from the [Auxiliary Links](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/#auxiliary-links) of the generated documentation. | `homepage` in `package.json` |
136| srcLink | Will link to the project source code. | `{projectHomepage}/blob/main/src/` |
137| srcDir | The directory in which `docgen` will search for TypeScript files to parse. | `'src'` |
138| outDir | The directory to which `docgen` will generate its output markdown documents. | `'docs'` |
139| theme | The theme that `docgen` will specify should be used for GitHub Docs in the generated `_config.yml` file. | `'mikearnaldi/just-the-docs'` |
140| enableSearch | Whether or not search should be enabled for GitHub Docs in the generated `_config.yml` file. | `true` |
141| enforceDescriptions | Whether or not descriptions for each module export should be required. | `false` |
142| enforceExamples | Whether or not `@example` tags for each module export should be required. (**Note**: examples will not be enforced in module documentation) | `false` |
143| enforceVersion | Whether or not `@since` tags for each module export should be required. | `true` |
144| tscExecutable | The path to the TypeScript compiler executable that docgen should use when invoking the compiler programmatically. | `'tsc'` |
145| exclude | An array of glob strings specifying files that should be excluded from the documentation. | `[]` |
146| parseCompilerOptions | tsconfig for parsing options (or path to a tsconfig) | {} |
147| examplesCompilerOptions | tsconfig for the examples options (or path to a tsconfig) | {} |
148
149## FAQ
150
151**Q:** For functions that have overloaded definitions, is it possible to document each overload separately?
152
153**A:** No, `docgen` will use the documentation provided for the first overload of a function in its generated output.
154
155## License
156
157The MIT License (MIT)