40 - Add mdx template to use in storybook

[MellyGray]

What this PR does / why we need it:

This PR adds a template in .mdx format for creating the documents for the elements on the Design System in Storybook. This template is intended to be used with the design system elements, not necessary for the rest of the components of the SPA.

Also the template is applied to the existing Button and DropdownButton components

Which issue(s) this PR closes:

• Closes Add mdx template for the Storybook documentation of the design system elements #40

Special notes for your reviewer:

I tried to theme storybook with Dataverse branding but seems to be an opened issue with Storybook 7. The theming gives an error and doesn't show .mdx files of the storybook, guess we'll need to try again in the future.

A part from that I just create the .mdx template and I applied it to the existing Design System stories

Suggestions on how to test this:

npm run storybook

Go to http://localhost:6006

The template is the DocsTemplate file on top and in the UI section you can see the rest of the Design System elements

Does this PR introduce a user interface change? If mockups are available, please link/include them here:

None

Is there a release notes update needed for this change?:

No

Additional documentation:

[pdurbin]

This seems fine. I ran it locally. I'm clicking "Approve" but I'll leave it in "Ready for Review" in case @ekraffmiller or others would like to take a look.

I'm slightly confused about how the template is to be used. I assume we would do something like this:

cd src/stories/ui
mkdir new-component
cp DocsTemplate.mdx new-component/NewComponent.mdx

Of course, if we ever change the template, existing components would be out of sync with those changes. We would need to update them. Still, I think a template is useful. Thanks!

[MellyGray]

@pdurbin that's really interesting. I wasn't thinking of an automation, just setting an standard to manually write the stories. I'll check if I can convert this template to an automatic documentation template because it's worth trying. Thanks!

[MellyGray]

@pdurbin @ekraffmiller

I changed the mdx template by a mix between MDX template + auto docs so the documentation is automatically generated with Jsdoc comments in the .stories. The advantage is that you don't need to do the copy paste approach for the docs template and that you can customize the template without having to change all the docs pages.

However, I discovered that Storybook autodocs is very limiting, you can only add stories related data, but you can't have independent blocks such as Usage Guidelines or SASS variables. So I had to add this data as a Jsdoc comment in the stories. I see this is why storybooks with huge customisation such as the one from Vibe doesn't use the auto docs and instead they create separated .mdx files. There were some requests in storybook repo to allow custom blocks in the docs but it doesn't seem to be their priority

I should probably have done the changes in a different branch in case we wanted to continue with the no-automated docs, but I forgot. In any case if we prefer the previous approach it should be easy to do a roll back

This is an example of the jsdoc comment for the usage guidelines and sass variables. What do you think?

[pdurbin]

I ran Storybook and poked around. I understand that this approach might be more limiting that .mdx files but it seems fine. Both seem fine that is. I'll let @ekraffmiller take a look before moving this to QA (or deciding to switch back to .mdx).