b39de05535
* reorganize docs apps * add README * fix directory * add condition for old docs * move docs-util to www * remove remaining docs-util * fixes of paths * fix scripts * path fixes * fix github actions * add build packages script
92 lines
2.4 KiB
Markdown
92 lines
2.4 KiB
Markdown
# docblock-generator
|
|
|
|
A CLI tool that can be used to generate TSDoc docblocks and OAS for TypeScript/JavaScript files under the `packages` directory of the main monorepo.
|
|
|
|
## Prerequisites
|
|
|
|
1. Run the `yarn` command to install dependencies.
|
|
2. Copy the `.env.sample` to `.env` and change the `MONOREPO_ROOT_PATH` variable to the absolute path to the monorepo root.
|
|
3. Run the `yarn build` command to build source files.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Generate for a specific file
|
|
|
|
Run the following command to run the tool for a specific file:
|
|
|
|
```bash
|
|
yarn start run /absolute/path/to/file.ts
|
|
```
|
|
|
|
### Generate for git-changed files
|
|
|
|
Run the following command to run the tool for applicable git file changes:
|
|
|
|
```bash
|
|
yarn start run:changes
|
|
```
|
|
|
|
### Generate for a specific commit
|
|
|
|
Run the following command to run the tool for a commit SHA hash:
|
|
|
|
```bash
|
|
yarn start run:commit <commit-sha>
|
|
```
|
|
|
|
Where `<commit-sha>` is the SHA of the commit. For example, `e28fa7fbdf45c5b1fa19848db731132a0bf1757d`.
|
|
|
|
### Generate for a release
|
|
|
|
Run the following command to run the tool on commits since the latest release.
|
|
|
|
```bash
|
|
yarn start run:release
|
|
```
|
|
|
|
### Clean OAS
|
|
|
|
Run the following command to clean up the OAS output files and remove any routes that no longer exist:
|
|
|
|
```bash
|
|
yarn start clean:oas
|
|
```
|
|
|
|
This command will also remove tags and schemas not used.
|
|
|
|
---
|
|
|
|
## How it Works
|
|
|
|
### Generating OAS
|
|
|
|
If a node is an API route, it generates OAS comments rather than TSDoc comments. The OAS comments are generated and placed in new/existing files under the `www/utils/generated/oas-output/operations` directory.
|
|
|
|
### Generating TSDoc Docblocks
|
|
|
|
If a note isn't an API Route and it complies with the specified conditions, TSDoc docblocks are generated for it.
|
|
|
|
Files under the `packages/medusa/src/api` or `api-v2` directories are considered incompatible, so any files under these directories won't have TSDoc docblocks generated for them.
|
|
|
|
---
|
|
|
|
## Common Options
|
|
|
|
This section includes options that you can pass to any of the mentioned commands.
|
|
|
|
### --generate-examples
|
|
|
|
If this option is passed, the tool will try to generate OAS examples. Currently, it will only try to generate JS Client examples.
|
|
|
|
cURL examples are always generated regardless of this option.
|
|
|
|
### --type
|
|
|
|
You can use this option to specify the type of docs to generate. Possible values are:
|
|
|
|
- `all`: (default) Generate all doc types.
|
|
- `docs`: Generate only TSDoc docblocks.
|
|
- `oas`: Generate only OAS docblocks/files.
|