At my recent project, we have been using SC5 Style Guide in its simplest way - documenting the view of the components. For that, we provided the needed HTML in the KSS code and so has received the rendered component library.
However, in the production code, these components appeared at the pages as a result of some templating transformations. Also, the project is massive and fast-developed, and the changes to the templates happened all the time. As a result, the style guide was always out of date.
At this project, I have solved the problem using advanced configuration of SC5 Style Guide. Below you can find the tricks and explanation.
The SC5 Style Guide parses the KSS documentation in your CSS (SASS, LESS) code, collects information about all the components and produces a JSON file with it. The documentation pages you can see are the Angular pages built on the information in this JSON.
As a value of this option, you can list the processing functions. The given indexes matter for the order in which these functions are applied to the data.
Check out the documentation for options.
In my projects, I used additional processors to operate custom KSS parameters and modify data.
In here the markup works as an input value for the given template. You can teach Style Guide to apply the template to the declared object and put the result as a markup to render. To do it you need a custom processing function mentioned above.
Combining this approach to the custom processors, you can store the code example for every compoentn in the markup KSS field.
This code runs a corresponding function for every selector in the knownComponents object. The matching DOM element(s) passed into the initializing function as a parameter.
You may have noticed that I suggest storing everything related to the component under the same folder. This is also relevant to the style-guide-related files.
However, the ‘component folder’ approach smoothes this situation. Storing everything (including the documentation) in the same place improves developer’s experience very much.
After ajusting the SC5 Style Guide, as shown above, you will get the double living documentation. Remember about the watching mode to re-generate the style guide on the file changes. It works as a nice development playground.
Also, last but not least, I would like to thank the community which made these things possible. I used the SC5 Style Guide features by other developers and so feel very grateful. You may see their names at the releases’ page. If you want yours to appear here, please contribute.