I want to compile/render Vue templates

[mirisuzanne]

No description provided.

[davisagli]

How do we want this to work?

The Vue docs actually use "docs" as an example of adding a custom type of block to a single-file component: https://vue-loader.vuejs.org/en/configurations/custom-blocks.html

Within the block, the format would be up to us. Also use sassdoc directives here?

I was thinking that we could try to introspect the component so that we can render some things even if the developer doesn't write explicit documentation (such as name, parameters). But this requires actually executing the js code, which can get tricky (do we require using webpack and providing your webpack configuration so we can use the loaders?). But if we want to actually render components inline as examples we have to do that somehow.

[davisagli]

As we discussed yesterday, being able to render examples of components is a pretty key feature.

That requires being able to execute the example in an environment that can import from other modules in the project. My current thinking about how to do this is:

1. Use a webpack plugin to render the examples once the build is done, and write the resulting doc data to a JSON file.
2. Add a directive from Herman to include pre-built JSON from that file.

This would be analogous to how we get data from Sass currently (Sass compilation produces JSON; Herman run consumes the JSON).

I think that given the difficulty and early status of this ticket compared to others in the 1.0 milestone, we should probably move this one to the stretch goals. Any objection?

[jgerigmeyer]

Sounds good. I agree that while a nice feature, this is not necessary for 1.0.

[jgerigmeyer]

Consider https://github.com/vuejs/component-compiler-utils?

[mirisuzanne]

@jgerigmeyer @chrisvfritz Here's a rough draft for syntax, roughly based on the SassDoc annotations. Happy for feedback!

https://gist.github.com/mirisuzanne/d1f6cd8733bb30cacf149620c1db78f9

[jgerigmeyer]

@chrisvfritz Okay, so here's a simple playground to work on Vue-Herman integration: oddbird/herman-test-project#4

I've added some notes there documenting what we've tried, and what I was planning to try next -- but you're certainly more knowledgable in this area, so feel free to ignore it and do whatever makes most sense!

[chrisvfritz]

Nice! I'll play around with this. 🙂