React-styleguidist: [Feature] Source examples from jsdoc comment code blocks

[jsg2021]

This project is awesome. Thank you for this!

It would be cool if we could write examples in a jsdoc code block in the class comment block instead of needing to make a sibling markdown file. Some examples are very short, making the markdown file feel silly. 😊

Again, this tool is amazing!

[sapegin]

I guess you can extend the @example tag to support code:

https://react-styleguidist.js.org/docs/documenting#external-examples-using-doclet-tags

[jsg2021]

I was imagining something like this:

/**
 * Regular documentation here...
 * 
 * ```js example
 * <Component .../>
 * ```
 *
 * @VariousTagsHere
 */
export default class Component extends React.Component {
...
}

The docs for @example show it pointing to another file. Which is fine, but this feature request is about inlining the example with the component. 😄

[sapegin]

That's what I'm saying: if you need that, you _can_ make @example tag to support code, not just a path.

[jgillick]

@jsg2021 I'm also interested in this and have started looking into how to update the code to make this work (I'm stuck at getting around the loaders). Are you trying to do the same? We could collaborate.

[jgillick]

The challenge I'm running into is to run the source code through the example-loader and have the result of that rendered in the examples.

Doing this, the example-loader function returns a string which is expected to be processed by require. So now I need to figure out how to appropriately execute this code. When I try to just run it through an eval, it throws the exception this.props.evalInContext is not a function.

I know that none of this is very helpful without seeing the code I'm talking about. After playing with it a little more I'll commit what I have to my forked version. If anyone has any pointers, please let me know.

[jsg2021]

I haven't looked into it. I've been happy with the external example file so far.

[jgillick]

If you're interested, I've gotten over the hurdle. Here's the rough version of the update, so far (I still need to clean it up and add unit tests and such):
https://github.com/styleguidist/react-styleguidist/pull/1171/files

[tomi]

This would be very beneficial for me as well.

[avionbg]

@jgillick your code breaks styleguidist markdown formatting, for example ```jsx static / noeditor doesn't work any more. Beside that there is no simple way to just show example code without rendering it in react (one could make an example like ```html, but that has another side-effect, examples are displayed twice. Only solution to this issues is to add an flag to the examples, something like ```jsx render.

[jgillick]

@avionbg Thanks for the feedback. The code is still just a working prototype. I'll give your suggestions a try this week.

Also, if anyone wants to assist me with this feature enhancement, I would love the help.

[avionbg]

@jgillick if you need any help or feedback just let me know, I like the idea of inline examples.

[mnaughto]

Is this something like what you had in mind @avionbg? I'm not sure if that was the right way to handle the case where there isn't a proper modifier.

I've been working with @jgillick on this, but we haven't had much time for it due to higher priorities.

[avionbg]

Yep this is it, at least from first impression, if I find any issues I'll let you know.

[stale[bot]]

😴 This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week without any further activity. Consider opening a pull request if you still have this issue or want this feature.