Originally published at: http://www.sitepoint.com/sassdoc-2-shiny-streamy-octopus/
A few months ago, I announced the first draft of SassDoc, a documentation tool for Sass. What a long road it has come since then. A couple of days a back, we finally released the second major version of SassDoc, entitled Shiny Streamy Octopus. We have been working on version 2 for months and spent a few weeks in beta, letting talented people test our product only to discover it was good enough to be released. Yay!
There are two reasons behind this second version of SassDoc: the first one was to clean the code base. I wrote the first draft of SassDoc mid-2014, and we’ve been working on some code of mine until then. While the code was not bad in itself, it was certainly not very scalable so we needed a much more robust base for the future. Fortunately, Valérian, Fabrice and Pascal are three very talented JavaScript developers who turned my old crappy code into a magnificent beast.
The second reason to push SassDoc v2, and the most important one, is to set up a rock solid base for us to build new features. In that way, this version does not bring many new features. It mostly consists of refactoring the whole code base, fixing bugs, improving APIs, deprecating obsolete features and all that crap that you can only do on major releases because of API breaks.
So what if I gave you a quick tour as well as some hints on how to upgrade from SassDoc v1 to Shiny Streamy Octopus?
New branding
SassDoc started as an experiment. At the very beginning, it was a playground for me to try Node.js. Soon enough, it was not an experiment anymore and actual people were using it on actual projects, such as the folks at ThoughtBot for Neat and Bourbon, as well as the front-end teams at The Guardian and Financial Times.
So we decided to give branding some love for this new version. I redesigned the whole site to have beautiful docs. We had Reda Lemeden design a logo for us, and Alix Lucas create an illustration to give SassDoc some visual strength.
That being said, we are well aware that not everybody will like the new branding. That’s fair enough. The site contains nothing but documentation, and the default theme can be customized. If you really don’t like the default theme, we have set everything up so you can build your own theme in a couple of minutes.
Now, if you feel like you can improve the default theme, we would gladly merge any thorough pull request so feel free to go nuts and suggest us any change!
API breaks
Let’s start with the real thing™: API breaks. Surprisingly enough, there are not as many major API changes as I first thought it would be. Depending on your project, you might have very little to nothing to change in your Sass files to transition to the new version.
C-style no more
I think the biggest change we made for the end user (a.k.a you) at this point was to deprecate C-style comments altogether. You know how I use to sell SassDoc by saying both C-style comments (/** ... */) and inline comments (///) were supported? Well this is no longer true. We decided that providing two ways to write docs was confusing and did not help much at the end of the day. Also, library writers using C-style comments would pollute users’ code with massive comment blocks, which is really not that cool.
To help moving from C-style to inline comments, our own Valérian wrote a little script. However pay attention! This is a raw find and replace that cannot be 100% bullet proof (actually this script cannot successfully convert file-level comments from C-style to inline). Be sure to carefully review your code to make sure everything is right.
For GNU sed:
Continue reading this article on SitePoint