Vue-Herman integration playground

[jgerigmeyer]

Playground for oddbird/sassdoc-theme-herman#168

[jgerigmeyer]

I see two aspects to the Vue-Herman documentation integration:

1. Pulling basic data from the Vue SFCs at Herman build-time, and making that data available to Herman as appropriate. For example, we need to know which components have Herman documentation at all, which group they're in, and probably some other basic information so that Herman knows where to include them in the rendered docs.

2. Rendering the actual Vue component <example>s with given props, etc.

At first, we were discussing having all of the Herman-related documentation in a separate SFC block (e.g. a <docs> tag). (Now we're talking about having much of the documentation inline in the component <script> tag -- a la https://gist.github.com/mirisuzanne/d1f6cd8733bb30cacf149620c1db78f9 -- which makes some of this moot.)

We started trying to tackle the second part -- rendering a Vue component with sample data/props.

Our first attempt used vue-server-renderer within Herman to try to grab a component by name and render it within Herman.

We pretty quickly ditched that approach, realizing there wasn't a good reason to require users to write their components in such a way that they could be compiled via node as well as in the browser. So, we thought, let's just have Herman render an iframe and render the Vue component <example> at runtime. I didn't have time to get very far trying this approach. As I understand it, there isn't a good way to access a locally-registered component, so either we'd have to require global registration (not ideal), or more likely make the component available to Herman via a webpack loader, or...?

I think the first step is sorting out what info needs to be made available to Herman at build-time, and what can just be available to Herman or the component at runtime.

I'm happy to help out as I'm able -- I know the internals of Herman pretty well, but have a much more cursory understanding of Vue and vue-loader, so take these thoughts with a large grain of salt!

[chrisvfritz]

I'm excited to work on this. 😃 Can you give an example of the JavaScript input Herman needs and how to provide it to Herman? For example, if Herman needs an array of objects, each object representing a component, what would those objects look like, minimally?

I think that would help me start building an integration (and know when it's working 😅). Does that make sense?

[jgerigmeyer]

That's a great question, and the answer is basically "that's up to us". But some rambling thoughts...

Currently Herman does not have parsing of anything other than Sass (we used to have a @markup annotation that parsed Nunjucks templates, but we replaced it with the Sass-driven @example njk annotation). So this would be the first case establishing a pattern for documenting in a non-Sass file. @mirisuzanne Am I correct that we're not talking about adding anything via a Sass file here; everything is defined directly in the Vue SFC?

In the end, the SassDoc parser sends Herman a data array, where each item is an object with info about that documented-thing (see http://sassdoc.com/data-interface/). I suppose Herman could just append to that list the Vue-documented items, in a format roughly matching what SassDoc provides? That would simplify the work Herman (and especially the templates) has to do to render everything properly.

That doesn't really answer your question of how to get the info to Herman. I imagine we'd want to add a top-level herman.vue option object. (Right now all Herman options are really nested in the SassDoc options under a herman key... though we have plans to eventually make Herman a broader tool that internally calls SassDoc, instead of the other way around.)

In this playground repo, the static SassDoc/Herman options are defined in the webpack config file (https://github.com/oddbird/herman-test-project/blob/master/webpack.config.js#L33-L56), and then passed into a custom sassdoc-webpack-plugin (https://github.com/oddbird/herman-test-project/blob/master/sassdoc-webpack-plugin.js) along with some options for webpack-compile-time Herman options (e.g. filepaths to generated assets: https://github.com/oddbird/herman-test-project/blob/master/webpack.config.js#L88-L94).

So... maybe the vue-loader or webpack-plugin or whatever generates a JSON file and we just pass that (or a path to it) into Herman as an option? Then Herman reads that file and inserts the data into the context before rendering the docs? (We're doing something similar already with extraDocs, customCSS, and sass.jsonfile options.)

That doesn't really solve the problem of actually rendering a Vue component -- I'm less clear on how Herman gets the necessary info there. At the very least a JS file with the Vue component to render at runtime, I'd think...

[jgerigmeyer]

I should add, there are a lot of moving parts here (and I'm not even 100% clear on what all they are!), but I'm happy to help out as I can -- especially on the Herman side. So if you can help get info to Herman (either in the form of JS objects, or filepaths to said objects), I'll be more useful in figuring out what Herman does with that data.

[chrisvfritz]

Thanks - that's great information! So maybe as a first step, I could generate an array of objects from .vue files, each object having a similar shape to the "item" documented here. Then later, we could figure out how we want to plug that into Herman and add more properties. Does that sound like a good first step?

[jgerigmeyer]

Yep, that sounds perfect! 👏

[mirisuzanne]

To answer the question for me…

Yes, at this point we're just talking about documentation from within the Vue SFC. There are some nice-to-have additions that we should keep in mind, but don't have to happen in this PR:

• Down the road it would be really cool to reference Vue components from Sass examples.
• It would be really lovely if Vue/Sass items could reference each other using the see or require annotations.