chore: two doc blocks to get custom docs added to the template #5917
Conversation
|
📚 Branch Preview Links🔍 First Generation Visual Regression Test ResultsWhen a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:
Deployed to Azure Blob Storage: If the changes are expected, update the |
| This template will likely be going away in the future, but for now it's here to help us get started. | ||
| <Subtitle /> | ||
|
|
||
| <sp-tabs id="component-doc-tabs" size="xl" selected="overview" auto label="Component Documentation"> |
There was a problem hiding this comment.
I'm thinking we might not need the tabs
| <sp-tab-panel value="examples" style={{ flexDirection: 'column' }}> | ||
| <SpectrumDocs tag="examples" /> | ||
| <Stories /> | ||
| </sp-tab-panel> |
There was a problem hiding this comment.
I don't think we need an examples section
| <sp-tab-panel value="usage" style={{ flexDirection: 'column' }}> | ||
| variations | ||
|
|
||
| <SpectrumDocs tag="usage" /> |
There was a problem hiding this comment.
I think this is where we put the examples from our old docs
| <sp-tab-panel value="overview" style={{ flexDirection: 'column' }}> | ||
| <Description /> | ||
| <Primary /> | ||
| <Controls /> |
There was a problem hiding this comment.
I would save the controls for last. Just let them see the component and some overall info about when to use.
| </sp-tab-panel> | ||
| <sp-tab-panel value="api" style={{ flexDirection: 'column' }}> | ||
| <ArgTypes /> | ||
| <ArgTypes /> |
There was a problem hiding this comment.
I think this is where we have an example with controls and code, so the API is interactive.
ok I have figured out how to make the doc blocks reusable AND get MDX rendering with functional JSX + Doc blocks
the docblocks have been converted to
Spectrum(Docs|Stories)and takes in an argument of the component stories imported* as ComponentStoriesforofandtag=[overview, usage, a11y, examples]. We can easily extend other tags to this pattern if we see needed as we get to more complex components.We have a super simple pattern for docs now with
component.usage.mdxandcomponent.a11y.mdx. The pattern is also set up foroverviewandexamplestags, but that can be on an as-needed basis or as we progress in garage week. I used progress-circle for most explorations so check it out.i like having the "description" in the subtitle doc block since most of them are short. it would be nice for components to have a quick blurb defining the component and then expand upon it in the description jsdoc above the meta tag in
component.stories.ts. lets chat more about this.This still remaining to be solved, the tabs hot linking correctly and the toc rendering the active tab. Also i think ive changed my mind on rendering emtpy tabs. I would like to build in logic that if all doc blocks in a section of the DocumentTemplate.mdx return empty or receive the fallback string (two potential approaches) that the tab and tab panel are removed from the autodocs. as well as if there is only the playground story (i.e. status light, asset) for a component that the examples tab does not render, ive found a cool article that had an interesting approach for an idea.
Read: doc blocks and document template blog post
Super stoked the templatizing of docs is working out!! its going to make writing docs soooo much lighter of a lift IMO