@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
md 157 lines 10.2 KB
Rendered Raw
1 # @effect/docgen
2
3 An opinionated documentation generator for Effect projects.
4
5 ## Installation
6
7 ```sh
8 npm 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
21 Whether 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
29 This library was inspired by the following projects:
30
31 - [docs-ts](https://github.com/gcanti/docs-ts)
32
33 ## Setup
34
35 1. (Optional) Add a `docgen.json` configuration file.
36
37 ```json
38 {
39 "$schema": "node_modules/@effect/docgen/schema.json"
40 }
41 ```
42
43 2. 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 v22.19 or above is required.
55
56 ### Example Configuration
57
58 The `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
105 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](#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
111 The `docgen.json` configuration file adheres to the following interface:
112
113 ```ts
114 interface 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
131 The 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
157 The MIT License (MIT)