{"id":14070153,"url":"https://github.com/Effect-TS/docgen","last_synced_at":"2025-07-30T07:30:40.374Z","repository":{"id":169788079,"uuid":"645315063","full_name":"Effect-TS/docgen","owner":"Effect-TS","description":"An opinionated documentation generator for Effect projects","archived":false,"fork":false,"pushed_at":"2024-11-25T11:03:07.000Z","size":578,"stargazers_count":34,"open_issues_count":2,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-25T11:32:33.272Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://effect-ts.github.io/docgen","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Effect-TS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mikearnaldi","gcanti"]}},"created_at":"2023-05-25T11:36:30.000Z","updated_at":"2024-11-25T11:02:28.000Z","dependencies_parsed_at":"2023-09-24T17:40:01.113Z","dependency_job_id":"4cfd0c2f-8339-499c-8fe8-21a8385ec63c","html_url":"https://github.com/Effect-TS/docgen","commit_stats":null,"previous_names":["effect-ts/docgen"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Effect-TS%2Fdocgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Effect-TS%2Fdocgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Effect-TS%2Fdocgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Effect-TS%2Fdocgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Effect-TS","download_url":"https://codeload.github.com/Effect-TS/docgen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228102560,"owners_count":17869878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-13T07:07:30.920Z","updated_at":"2024-12-04T11:31:22.877Z","avatar_url":"https://github.com/Effect-TS.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mikearnaldi","https://github.com/sponsors/gcanti"],"categories":["TypeScript"],"sub_categories":[],"readme":"An opinionated documentation generator for Effect projects.\n\n# Credits\n\nThis library was inspired by the following projects:\n\n- [docs-ts](https://github.com/gcanti/docs-ts)\n\n# Setup\n\n1. Install `@effect/docgen` as a dev dependency:\n\n```shell\npnpm add @effect/docgen -D\n```\n\n2. (Optional) Add a `docgen.json` configuration file.\n\n```json\n{\n  \"$schema\": \"node_modules/@effect/docgen/schema.json\"\n}\n```\n\n3. Add the following script to your `package.json` file:\n\n```json\n{\n  \"scripts\": {\n    \"docgen\": \"docgen\"\n  }\n}\n```\n\n\u003e [!WARNING]\n\u003e To use \"@effect/docgen\", Node.js v18 or above is required.\n\n## Example Configuration\n\nThe `docgen.json` configuration file allows you to customize `docgen`'s behavior. Here's an example configuration:\n\n```json\n{\n  \"exclude\": [\"src/internal/**/*.ts\"],\n  \"parseCompilerOptions\": {\n    \"noEmit\": true,\n    \"strict\": true,\n    \"skipLibCheck\": true,\n    \"moduleResolution\": \"Bundler\",\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\"],\n    \"paths\": {\n      \"@effect/\u003cproject-name\u003e\": [\"./src/index.js\"],\n      \"@effect/\u003cproject-name\u003e/test/*\": [\"./test/*.js\"],\n      \"@effect/\u003cproject-name\u003e/examples/*\": [\"./examples/*.js\"],\n      \"@effect/\u003cproject-name\u003e/*\": [\"./src/*.js\"]\n    }\n  },\n  \"examplesCompilerOptions\": {\n    \"noEmit\": true,\n    \"strict\": true,\n    \"skipLibCheck\": true,\n    \"moduleResolution\": \"Bundler\",\n    \"target\": \"ES2022\",\n    \"lib\": [\"ES2022\", \"DOM\"],\n    \"paths\": {\n      \"@effect/\u003cproject-name\u003e\": [\"../../src/index.js\"],\n      \"@effect/\u003cproject-name\u003e/test/*\": [\"../../test/*.js\"],\n      \"@effect/\u003cproject-name\u003e/examples/*\": [\"../../examples/*.js\"],\n      \"@effect/\u003cproject-name\u003e/*\": [\"../../src/*.js\"]\n    }\n  }\n}\n```\n\n# Supported JSDoc Tags\n\n| Tag           | Description                                                                                                                                                                                                                                            | Default   |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |\n| `@category`   | Groups associated module exports together in the generated documentation.                                                                                                                                                                              | `'utils'` |\n| `@example`    | Allows usage examples to be provided for your source code. All examples are type checked using `ts-node`. Examples are also run using `ts-node` and the NodeJS [assert](https://nodejs.org/api/assert.html) module can be used for on-the-fly testing. |           |\n| `@since`      | Allows for documenting most recent library version in which a given piece of source code was updated.                                                                                                                                                  |           |\n| `@deprecated` | Marks source code as deprecated, which will ~~strikethrough~~ the name of the annotated module or function in the generated documentation.                                                                                                             | `false`   |\n| `@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.                          |           |\n| `@ignore`     | Prevents `docgen` from generating documentation for the annotated block of code.                                                                                                                                                                       |           |\n\nBy 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.\n\n# Configuration\n\n`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.\n\nThe `docgen.json` configuration file adheres to the following interface:\n\n```ts\ninterface Config {\n  readonly projectHomepage?: string;\n  readonly srcDir?: string;\n  readonly outDir?: string;\n  readonly theme?: string;\n  readonly enableSearch?: boolean;\n  readonly enforceDescriptions?: boolean;\n  readonly enforceExamples?: boolean;\n  readonly enforceVersion?: boolean;\n  readonly exclude?: ReadonlyArray\u003cstring\u003e;\n  readonly parseCompilerOptions?: string | Record\u003cstring, unknown\u003e;\n  readonly examplesCompilerOptions?: string | Record\u003cstring, unknown\u003e;\n}\n```\n\nThe following table describes each configuration parameter, its purpose, and its default value.\n\n| Parameter               | Description                                                                                                                                                                         | Default Value                 |\n| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |\n| 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`  |\n| srcDir                  | The directory in which `docgen` will search for TypeScript files to parse.                                                                                                          | `'src'`                       |\n| outDir                  | The directory to which `docgen` will generate its output markdown documents.                                                                                                        | `'docs'`                      |\n| theme                   | The theme that `docgen` will specify should be used for GitHub Docs in the generated `_config.yml` file.                                                                            | `'mikearnaldi/just-the-docs'` |\n| enableSearch            | Whether or not search should be enabled for GitHub Docs in the generated `_config.yml` file.                                                                                            | `true`                        |\n| enforceDescriptions     | Whether or not descriptions for each module export should be required.                                                                                                              | `false`                       |\n| enforceExamples         | Whether or not `@example` tags for each module export should be required. (**Note**: examples will not be enforced in module documentation)                                         | `false`                       |\n| enforceVersion          | Whether or not `@since` tags for each module export should be required.                                                                                                             | `true`                        |\n| exclude                 | An array of glob strings specifying files that should be excluded from the documentation.                                                                                           | `[]`                          |\n| parseCompilerOptions    | tsconfig for parsing options (or path to a tsconfig)                                                                                                                                | {}                            |\n| examplesCompilerOptions | tsconfig for the examples options (or path to a tsconfig)                                                                                                                           | {}                            |\n\n# FAQ\n\n**Q:** For functions that have overloaded definitions, is it possible to document each overload separately?\n\n**A:** No, `docgen` will use the documentation provided for the first overload of a function in its generated output.\n\n# License\n\nThe MIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEffect-TS%2Fdocgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEffect-TS%2Fdocgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEffect-TS%2Fdocgen/lists"}