-
-
Notifications
You must be signed in to change notification settings - Fork 316
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update to utilize JSDocs #351
Comments
https://github.com/carbon-design-system/sveld is the most promising looking option so far and might give us more than just what jsdoc can provide. |
Suggested by Rhys on Discord:
|
Ideally, we want to avoid duplication; if we are documenting the usage of a component within the component, ideally, we would be able to generate the https://skeleton.brainandbonesllc.com/components/* docs from them, obviating the need for manual doc generation. |
From Nik in Discord Throwing this out for general input: Goal is to have single source of truth for things like props/methods of a component, which can be derived from the code using JSdoc so that it helps intellisense as well as the docs site. Post process insertion of auto generated content of pnpm build is not an option due to chunking Most other doc sites use Markdown in one way or another for the human generated portions (Usage, examples etc) - which in theory should make it more accessible for contributors to help with. Then there is all the full on solutions like storybook and histoire for auto genning doc sites at the component level and things like JSDoc at the code level. Histoire looks the best out of these as it is Vite based and integrates well with Svelte and also handles things like CSS displays - https://svelte3.examples.histoire.dev/story/src-introduction-story-js All that said, pretty much every solution looks like a big revamp of what we have (unless we go pre-process) - so i would love any other solutions thrown in that other people have used. |
@ryceg let me know if you wish to take this on as discussed on Discord. I'll assign to you. I'd advise you create a draft PR asap so Nik and I can monitor progress and provided feedback. @niktek's PR is available for here if you two want to work together on the Svelte integration, perhaps in parallel: I'm sure he wouldn't mind answering questions about what he setup. Otherwise I'll return to this mostly likely next release cycle, as my docket is going to be fairly full between now and the middle of next week (next release). |
I'll take it! I love docs |
Assigned! |
So Sveld is mostly fit for purpose, but there's a couple deficits that get in the way of us using it fully for documentation, which I think is a very good long-term goal to aim for. The Sveld interpreter is notably missing many of the JSDoc tags, which is working against us, but isn't actually a dealbreaker- it just interprets everything as an extension of the description, and includes new lines. If we use JSDoc tags, then we can use Sveld has a rudimentary version of this to handle slots; |
@ryceg see my response on Discord. |
@niktek @ryceg I've completed my review of Sveld and kicked the tires on it in test project. Here's some of my notes and findings. @extend for Parent/Child relationshipshttps://github.com/carbon-design-system/sveld#extends
If I'm reading this correctly, is this not the intended way to denote that this is a child component? Regardless I'm feeling less confident about the need for Use of
|
@ryceg One quick follow up question - the only thing I did use was |
@niktek @ryceg writing up my notes based on the current changes to Nik's PR here:
Doc Shell
sveldMapper.ts
Settings Updates (DocsShellSettings)
types.ts
What's Not WorkingMost is working well, but here's a few things of note:
|
@niktek @ryceg FYI I've completed another round of updates and update Elements, Components, Actions, and Utility documentation pages to the new settings format. I've not yet began updating the JSDocs comments per each component yet, but that's what we can divvy up soon. For now I've just ensured everything is "wired up". A few notable updates:
Still on my list to do:
Check the PR for the latest! |
@niktek @ryceg FYI I've pinged the vite-sveld-plugin author on Nik's PR to see if we can get some movement on an update: Likewise I've pointed out that Sveld has updated to include two major features we need:
It's critical we have these. If we do not see movement on the plugin, we may need to fork and handle this ourselves. Additionally, we should revisit using Sveld directly as a Rollup plugin, since it seems to be technically possible. I believe this would cut out the plugin as the middleman here. UPDATE The plugin maintainer has responded and will look to update to the latest version. We should still aim to use Sveld as a Rollup plugin though, as it's the path of least resistance. |
I've pushed a few more adjustments today, including: types.ts
sveldMapper.ts
I think aside from getting Sveld updated to support Event/Slot descriptions, we've got everything we need to begin documenting each Skeleton feature using the auto-doc system! |
@niktek @ryceg Unfortunately it doesn't appear we're going to be able to use Sveld's restProps feature. We always divide the Here's an example of this scenario in the File Button component: However, this seems like something we could easily build into the existing DocShell settings. With either a boolean for mentioning it's used, or follow Sveld's lead and specify the element that restProps is applied to. I'm keen to use the latter. EDIT I'll push this shortly, but here's how it'll operate for the four or so components that need this:
The UI, which links to here: |
@niktek @ryceg I've pushed one more set of updates which, unless we get some feedback from the Sveld author, will be what we merge later today. This includes:
The Sveld author has responded, but nothing we can act on yet. Long story short, when using Sveld in our project the capabilities are more limited and don't match the Sveld Playground. EDIT Quick update, we were able to get a version of the multi-line comments working that works for @slot descriptions, but it still requires the proceeding Make sure you catch up on the conversation as it's progressed today, starting from here: EDIT 2 I've pushed an update to use the production release of |
Some recommendations based on my usage of the current implementation:
|
@niktek @ryceg Here's my updates from my audit of Nik's PR. These changes have now been been committed and pushed. FYI, here's what happens when we use
Svelte Components
Utilities
|
Pushed out a couple more quick changes:
This has now been merged into the |
Describe what feature you'd like. Pseudo-code, mockups, or screenshots of similar solutions are encouraged!
@niktek confirmed we can use JSDocs comments to add additional intellense information for component props. We should aim to implement these asap
What type of pull request would this be?
Enhancement
Any links to similar examples or other references we should review?
If possible we should look into a way to share the same data between the JSDocs comment AND the docs page UI description, so we're not repeating ourselves. Assuming this is possible.
Reference PRs
Sveld Documentation Progress
Chris:
Nik:
Rhys:
The text was updated successfully, but these errors were encountered: