docs: autogenerated typedoc reference #2308
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -29,7 +29,9 @@ We have included `launch.json` files that store configuration for `vscode` debug | |
|
|
||
| See the [Docs README](https://github.com/slackapi/node-slack-sdk/blob/main/docs/README.md) for information on how the docs site work. | ||
|
|
||
| The reference docs for each package is independent of the others. They're generated using `typedoc` and `typedoc-plugin-markdown`. In each package's `package.json` there's a `docs` command that generates reference docs for that package based on the configuration settings found in `/package-name/typedoc.json`. | ||
|
|
||
| The script places the reference markdown files in `/reference/package-name`. | ||
|
|
||
| ### 🚀 Releases | ||
| _For beta releases, see [**Beta Releases**](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-beta-releases) section below_ | ||
|
|
@@ -50,38 +52,40 @@ Releasing can feel intimidating at first, but rest assured: if you make a mistak | |
|
|
||
| 4. For each package to be released, run `npm run test` to verify that tests are passing and code is free of linting errors. | ||
|
|
||
| 5. Generate the reference docs for that package by running `npm run docs`. | ||
|
|
||
| 6. On your new branch, bump the version(s) in `package.json` (see [Versioning and Tags](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-versioning-and-tags)) | ||
|
|
||
| - Make a single commit for the version(s) bump, following the format in: ([Example](https://github.com/slackapi/node-slack-sdk/commit/1503609d79abf035e9e21bad7360e124e4211594)) | ||
|
|
||
| - Create a pull request for the version change ([Example](https://github.com/slackapi/node-slack-sdk/pull/1059)) | ||
|
|
||
| - Add appropriate labels on the PR, including `release` | ||
|
|
||
| 7. Once the PR has been approved and tests have passed, merge it into the main repository. | ||
|
|
||
| - Check out your local `main` branch and update it to get the latest changes: `git checkout main && git pull origin main` | ||
|
|
||
| - Add a version tag (ie, `git tag @slack/[email protected]`) | ||
|
|
||
| - Push the new tag up to origin: `git push --tags origin` | ||
|
|
||
| 8. Publish the release to npm | ||
| - To publish, you need to be a member of the `slack Org` on npm and set up 2-Factor Auth with your passsword generator of choice. Before you can publish with npm, you must run `npm login` from the command line. | ||
|
|
||
| - As the final validation, within the package directory (ex: `packages/types`), run `mv package-lock.json package-lock.json.bk && rm -rf node_modules/ dist/ && npm i && npm test && npm pack` and confirm if there are `*.js`, `*.d.ts` files under the `dist` directory. | ||
|
|
||
| - Run `npm publish . --otp YOUR_OTP_CODE`. To generate an OTP (One Time Password), use your password generator of choice (Duo, 1Password) | ||
|
|
||
| 9. Close GitHub Milestone(s) | ||
|
|
||
| - Close the relevant GitHub Milestone(s) for the release(s) | ||
|
|
||
| - Check the existing GitHub Milestones to see if the next minor version exists. If it doesn't, then create a GitHub Milestone for new issues to live in. Typically, you'll create a new minor version - however, if there are any bugs that need to be carried over from the current GitHub Milestone, you could make a Milestone for a patch version to reflect those issues | ||
|
|
||
| - Move any unfinished, open issues to the next GitHub Milestone | ||
|
|
||
| 10. Create GitHub Release(s) with release notes | ||
|
|
||
| - From the repository, navigate to the **Releases** section and draft a new release | ||
|
|
||
|
|
@@ -93,7 +97,7 @@ Releasing can feel intimidating at first, but rest assured: if you make a mistak | |
|
|
||
| - Once the release notes are ready, click the "Publish Release" button to make them public | ||
|
|
||
| 11. Communicate the release (as appropriate) | ||
|
|
||
| - **Internal** | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| { | ||
| "$schema": "https://typedoc.org/schema.json", | ||
| "entryPoints": ["src/index.ts"], | ||
| "plugin": ["typedoc-plugin-markdown"], | ||
| "outputs": [ | ||
| { | ||
| "name": "markdown", | ||
| "path": "../../docs/content/reference/cli-test" | ||
| } | ||
| ], | ||
| "skipErrorChecking": true, | ||
| "useCodeBlocks": true, | ||
| "logLevel": "Error", | ||
| "readme": "none", | ||
| "gitRevision": "main", | ||
|
There was a problem hiding this comment. 🗣️ This seems reasonable to me for links that match: Updating this to use the package version might be useful too since we're running this with the release process, but we can revisit this later I think: https://typedoc.org/documents/Options.Input.html#includeversion There was a problem hiding this comment. the one thing is that this would make bookmarks to those links out of date without the user always noticing (or maybe that's a me thing) There was a problem hiding this comment. Hmm I was imagining bookmarks would be more common to a page like: Which will be refreshed with each tagged version 🚀 Between versions the code referenced on a specific line of That's a bit more fragile to me and might be confusing if the reference links don't line up with the tagged version, but that might also be motivation to release more often... 👁️🗨️ There was a problem hiding this comment. oh! i see. okay i'm sold |
||
| "excludePrivate": true, | ||
| "excludeProtected": true, | ||
| "excludeInternal": true, | ||
| "hideGenerator": true, | ||
| "jsDocCompatibility": true, | ||
| "hidePageHeader": true, | ||
| "entryFileName": "index", | ||
| "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test-d.ts"] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| { | ||
| "$schema": "https://typedoc.org/schema.json", | ||
| "entryPoints": ["src/index.ts"], | ||
| "plugin": ["typedoc-plugin-markdown"], | ||
| "outputs": [ | ||
| { | ||
| "name": "markdown", | ||
| "path": "../../docs/content/reference/logger" | ||
| } | ||
| ], | ||
| "skipErrorChecking": true, | ||
| "useCodeBlocks": true, | ||
| "logLevel": "Error", | ||
| "readme": "none", | ||
| "gitRevision": "main", | ||
| "excludePrivate": true, | ||
| "excludeProtected": true, | ||
| "excludeInternal": true, | ||
| "hideGenerator": true, | ||
| "jsDocCompatibility": true, | ||
| "hidePageHeader": true, | ||
| "entryFileName": "index", | ||
| "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test-d.ts"] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this makes the most sense since the maintainer will be in the proper package subdirectory from the previous step, but may be wrong!