Extract props/slots/events documentation from source code

[tbusser]

Clear and concise description of the problem

I would like Histoire to extract the props/slots/events documentation from the source code and display it as documentation within Histoire. By reusing the documentation in the source code it will prevent me from having to write it again somewhere else. This will ensure there is a single source of truth for the documentation of these props/slots/events.

Suggested solution

There is a package which can extract this information from your Vue source code, it is called vue-docgen-api. This outputs an object containing the information it was able to find in the code. With this object it should be possible to show the documentation for props/slots/events in Histoire.

Alternative

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that requests the same feature to avoid creating a duplicate.

[elevatebart]

Really good idea @tbusser I need to get this to work.

@Akryum I will probably do most of the backend work.
I am counting on your designers' talents to make it look good once we have the data.

[sheremet-va]

Maybe we can use https://github.com/johnsoncodehk/volar/tree/master/packages/vue-component-meta ?

[TO-koswald]

Is this still on the horizon?
This is the only major thing that's missing for us to switch from storybook.
Overall very pleased with histoire.

[elevatebart]

Hello @TO-koswald

It is still on the horizon. I have been kinda swamped lately.
I dropped the ball a little.
I am getting back on it as we speak.

I will have more news about it in a few hours.

But first, one question:

Since a .story.vue file is not necessarily associated with one component only, how would you explicit this connection so this documentation can find its place in the navigation? Would you have a separate story/page for component data? Would you have a special import?

Thanks for your insights.
Bart

[TO-koswald]

Hey @elevatebart, good to hear about this update.

I quite like the way storybook solved it by just adding it to the controls. Kinda like that:

They also generate a table in the Docs tab:

I much prefer to have everything as automatic as possible and not use a special import, but detect which components are used on the root level (I think histoire already does that) and then extract the docgen info and apply it to the controls.
For docs a similiar table as to what storybook does would be awesome.

[BombaraGianluca]

Hi, are there updates?
In this moment i use storybook for stories (Vue3) but i love Historie.
I would to migrate but my team needs props documented.
Thanks :-)

[Rolanddoda]

Sad that props, events, slots, etc are not auto-documented.
This would be a game changer!

Any update if this is going to be added and if yes, what's the current state?

[elevatebart]

If I get around to it, it will be added.

Here is what I have so far:

• Right now props/slots extraction is done at runtime directly on the client
• Parsing components and decorating them with extracted metadata can be done using https://github.com/andrewcourtice/vite-plugin-vue-docgen or a plugin that does something similar.
• We should detect Components in stories by walking the virtual DOM at runtime. Since this will happen in the browser, and the docgen-api works on the server. We have to suppose that component docs will be available.
• Since it could add significant weight on a generated histoire website, it needs to be an option. All the serialized props for every component would have to be packaged to be available at runtime.

Work in progress,
I still am 100% on Cypress.io new website for now.

[BombaraGianluca]

Any update if this is going to be added and if yes, what's the current state?
Thanks
I love histoire and this feacture is really important to migrate from storybook.

[elevatebart]

Hello @BombaraGianluca

Would you be interested in trying your hand at implementing it?

The biggest challenge I see is that prop detection is done client side on histoire right now and it would have to be at least started on the server side to sue a file parser like vue-docgen-api or vue-component-meta.

[Evertvdw]

Would also love this feature, currently looking at histoire vs storybook as to which we will use for documenting our design system.

When implementing this feature it would be nice if it also would honor extends of props. Example:

export interface LocalProps extends SomeImportedInterface {
	/**
	 * Make it an only text button
	 * @default false
	 */
	text?: boolean;
}

Currently the storybook auto generate feature ignores the imported interface, if histoire could have this feature it would be a big plus over using storybook.

[floroz]

Currently the storybook auto generate feature ignores the imported interface, if histoire could have this feature it would be a big plus over using storybook.

that is because of vue-docgen-api.

With vue-component-meta you would be able to parse and extract metadata from imported types, complex types, union etc, while also extracting JSDoc from the new compiler macros.

Auto-docs is a massive feature for teams, particularly those wanting to create component libraries where automatically extracting props/events/slots/exposes and adding full JSDoc annotation, creates a great documentation experience for teams.

Storybook has a lot of overhead and limited support for some Vue features, would be amazing to see Histoire adding auto-docs generation.

I wonder whether it should be something that allow customization? Storybook uses the @storybook/blocks to allow you customize a template where the metadata is extracted, but you are in control on the order/display of each individual section, while also enhancing with your own content the "Docs" page.