Living Style Guide
- Problem: For front-end contributors we needed a way to produce easily maintained, up-to-date documentation.
- Solution: I wrote a Python script that extracts code and Markdown comments in Sass partials, packaging it into a single documentation file.
Because documentation and style guides are often out of date before they’re finished there’s been a trend of building documentation from comments directly embedded in the source code. Scripts like Kalei, KSS, and Living Style Guide are but a few.
Not satisfied with the existing scripts, and eager to learn more Python, I decided to write my own. Like the others this uses Markdown comments but I’ve added options to display code snippets, html snippets or both.
The downside was that I was spending time recoding functionality already handled by the previously mentioned scripts, and following the source order paths of the Sass partials required the help of a colleague. But we’re now in complete control of what and how it gets displayed and new members to the team are able to get up to speed much quicker than before.