docs: autogenerated typedoc reference #2308
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
✅ All tests successful. No failed tests found. Additional details and impacted files@@ Coverage Diff @@
## main #2308 +/- ##
=======================================
Coverage 92.74% 92.74%
=======================================
Files 38 38
Lines 10660 10660
Branches 687 687
=======================================
Hits 9887 9887
Misses 761 761
Partials 12 12
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
| @@ -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. 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)) | |||
| 5. Generate the reference docs for that package by running `npm run docs`. | |||
There was a problem hiding this comment.
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!
zimeg
added
docs
zimeg
changed the title
There was a problem hiding this comment.
@lukegalbraithrussell Super impressive changeset and I hold excitement! 📚 ✨
Requesting a few changes before merging this but am wanting to hear what you think about a few things too:
- Can
typedocbe kept with development dependencies? - Do we want to use versioned permalinks for code references?
Some other suggestions are more preference but please do keep me updated 👾
| { | ||
| type: 'autogenerated', | ||
| dirName: 'reference', | ||
| }, |
| "useCodeBlocks": true, | ||
| "logLevel": "Error", | ||
| "readme": "none", | ||
| "gitRevision": "main", |
There was a problem hiding this comment.
🗣️ This seems reasonable to me for links that match:
Defined in: [src/WebClient.ts:133](https://github.com/slackapi/node-slack-sdk/blob/main/packages/web-api/src/WebClient.ts#L133)
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
Defined in: [src/WebClient.ts:133](https://github.com/slackapi/node-slack-sdk/blob/49f8acc669f55335541561c50559aaf769d1efff/packages/web-api/src/WebClient.ts#L133)
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 main might change without the reference in docs updating otherwise, and might cause these links to point to missing lines or files altogether!
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
|
@zimeg thanks for your feedback! Fixed the issues |
There was a problem hiding this comment.
@lukegalbraithrussell Thanks too for making those changes!
I do remain biased towards versioned code reference but don't think that should block us from these improvements as is - please feel free to merge when the time is right 🤖 ✨
And in rambling now, this makes me want to improve our jsdoc so much! 📚 🔍
Summary
My last promise to Fil
Previously, we used a docusaurus typedoc plugin that was hard to navigate with our multiple packages. It also doesn't work for our planned setup of only keeping markdown files in this repo.
each package has a
docsscript in itspackage.jsonthat generates the reference docs for that package.After merge
.gitignoredRequirements (place an
xin each[ ])