From 6b97468c9eabfc190002fd266c3ef9591938d195 Mon Sep 17 00:00:00 2001 From: Nick Wylynko Date: Fri, 18 Jul 2025 18:37:25 -0400 Subject: [PATCH 1/2] Update guides --- .typedoc/README.md | 2 +- docs/CICD.md | 2 +- docs/CONTRIBUTING.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.typedoc/README.md b/.typedoc/README.md index c1bd82efd66..68ddcc3a807 100644 --- a/.typedoc/README.md +++ b/.typedoc/README.md @@ -71,7 +71,7 @@ To generate the Typedoc MDX files inside `.typedoc/docs` run the following scrip pnpm run typedoc:generate ``` -The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents will be pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) in CI. You can use it to debug and tweak the output locally before it gets published. +The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents will be pushed to [clerk/clerk-docs](https://github.com/clerk/clerk-docs/tree/main/clerk-typedoc) in CI. You can use it to debug and tweak the output locally before it gets published. ### Adding a package to the Typedoc output diff --git a/docs/CICD.md b/docs/CICD.md index 7becad9b5b1..8e474a8458b 100644 --- a/docs/CICD.md +++ b/docs/CICD.md @@ -14,7 +14,7 @@ A stable release will be triggered every time the "ci(repo): Version packages" P - All SDKs will be published to `npm`, except for those found in the excluded packages list in `.changeset/config.json`, or any packages with `private: true` set in their `package.json` file. - A workflow dispatch will be triggered to update the `clerkjs-proxy` worker in `clerk/sdk-infra-workers`. - A workflow dispatch will be triggered to update the `@clerk/nextjs` version in `clerk/dashboard`. -- A workflow dispatch will be triggered to update the generated docs in `clerk/generated-typedoc`. +- A workflow dispatch will be triggered to update the typedoc generated docs in `clerk/clerk-docs`. For details regarding the package versioning/publishing process, refer to the [Publishing docs](https://github.com/clerk/javascript/blob/main/docs/PUBLISH.md). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a12d1a48c6a..ac9b6376572 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -182,7 +182,7 @@ As explained in [documenting your changes](#documenting-your-changes), we use JS Locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typdoc/docs`. -These files are pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) and then used on Clerk's docs. In the docs you can access the files by using a `` component. +These files are pushed to [clerk/clerk-docs](https://github.com/clerk/clerk-docs/tree/main/clerk-typedoc) and then used on Clerk's docs. In the docs you can access the files by using a `` component. So if you find a typo that's inside a Typedoc file, you'll need to edit the source file, [open a PR](#opening-a-pull-request), and get it merged to `main`. You can preview your changes with the aforementioned `pnpm typedoc:generate` command. From 3961d00c4444814ff3f608ab21b9b9393995b45a Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 22 Jul 2025 16:31:21 -0400 Subject: [PATCH 2/2] review --- docs/CONTRIBUTING.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ac9b6376572..013f49829b7 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -178,13 +178,23 @@ If your change can't only be tested by unit tests, you should add/edit an integr ### Authoring Typedoc information -As explained in [documenting your changes](#documenting-your-changes), we use JSDoc to annotate our public API surface. We then use [Typedoc](https://typedoc.org/) to autogenerate docs from these comments. +As explained in [documenting your changes](#documenting-your-changes), we use JSDoc to annotate our public API surface. We then use [Typedoc](https://typedoc.org/) to autogenerate MDX docs from these comments. -Locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typdoc/docs`. +For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this guide](https://www.notion.so/clerkdev/Typedoc-JSDoc-1df2b9ab44fe808a8cf2c9cca324ea89?source=copy_link). -These files are pushed to [clerk/clerk-docs](https://github.com/clerk/clerk-docs/tree/main/clerk-typedoc) and then used on Clerk's docs. In the docs you can access the files by using a `` component. +To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first: -So if you find a typo that's inside a Typedoc file, you'll need to edit the source file, [open a PR](#opening-a-pull-request), and get it merged to `main`. You can preview your changes with the aforementioned `pnpm typedoc:generate` command. +Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, a PR will [automatically](https://github.com/clerk/clerk-docs/blob/main/.github/workflows/typedoc.yml) be opened in `clerk-docs` to merge in the Typedoc changes. + +Typedoc output is embedded in `clerk-docs` files with the `` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `` component linked to the `./clerk-typedoc/clerk-react/use-auth.mdx` file, like: + +```mdx + +``` + +Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-). + +Then, to preview how the `` component renders, the `clerk-docs` PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs). ## Opening a Pull Request