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:
find . -name '*.s[ac]ss' -exec sed -i 's,^/\*\*,///,;s,^ *\*\*/,////,;s,^ *\*/,///,;s,^ *\*,///,' {} +For Mac/BSD sed:
find . -name '*.s[ac]ss' -exec sed -i ' 's,^/\*\*,///,;s,^ *\*\*/,////,;s,^ *\*/,///,;s,^ *\*,///,' {} +Windows users, I suggest you try the GNU version in a Git shell.
Bracketize default values
Another important changes we made, that unfortunately cannot be automagically fixed by a simple shell script, is to use brackets ([]) rather than parentheses (()) for default values in @property and @parameter annotations (as well as their aliases of course). Until then, you would write something like this:
/// @param {String} $foo ('bar') - BazThis annotation means the documented item accepts a $foo argument, whose default value is the string bar. This does not work anymore. From now on, you have to use brackets, turning your code into:
/// @param {String} $foo ['bar'] - BazIt was a bit of a tough choice to make but we encountered some parsing issues when using parentheses as wrappers. Think of default values that contain parentheses, such as function calls (e.g. length()). From time to times, our parser choked and did not grab the correct value. Long story short, we decided to go the safest way and use brackets.
To convert those parentheses to brackets, Valérian (again) wrote a little script. And again, this is dummy search and replace, so be sure to review everything carefully especially since the script will convert (length($list)) to [length[$list]]. As I said, not bulletproof.
For GNU user:
find . -type f -name '*.s[ac]ss' -exec sed -ri '/@param|@prop/y/()/[]/' {} +For Mac/BSD users:
find . -type f -name '*.s[ac]ss' -exec sed -Ei ' '/@param|@prop/y/\(\)/\[\]/' {} +Windows users, I suggest you try the GNU version in a Git shell.
Output folder
Once, a couple of weeks ago, we had someone come over on GitHub and tell us he had wiped his entire working directory. Crap. It turns out he didn’t read the wiki (we did not have the dedicated site back then) where we warned against the destination folder being wiped out when running SassDoc. For his defense, it was not his fault entirely: we did not prompt or abort if the destination folder was not empty. I believe we messed up.
Shortly after, we pushed something with flags to force / prompt you with this. It worked better, it prevented any incident, it made the API a bit more complex. So we went the very easy way, the one I discarded for a long time because I didn’t really like it: we made SassDoc always output its own directory (./sassdoc) at the current path, with an option (--dest) to change this location.
So, now using SassDoc has gotten much simpler. The CLI API only asks for a source folder. The destination folder can be set with --dest, and will default to ./sassdoc if omitted.
To document a specific folder, such as stylesheets/, pass it as the first argument. To change the path to the destination folder such as docs/sass/, simply use the --dest option.
sassdoc stylesheets/ --dest ./docs/sass/New features
I said this version was essentially a major refactoring of the API, but we obviously took it as an opportunity to introduce new minor features.
More powerful API
We’ve seen in the previous section how we tweaked the API to make everything a bit more robust (especially regarding the output folder). You will be pleased to know we also made it possible for you to define exclude patterns so you can prevent SassDoc from parsing some files and/or folders.
For instance, you could intimate SassDoc to parse your stylesheets folder but to omit vendor stylesheets. Using nothing but the CLI API, that would look like this (quotes matter):
sassdoc stylesheets/ '!stylesheets/vendors/*'Now you can use the configuration file to set this up in a more persistent fashion, like so:
exclude:
- ./stylesheets/vendors/*Along the same lines, it is now possible to pipe a stream into SassDoc. To put it simply q , you can now run SassDoc on a file from within the console. For instance:
cat stylesheets/utils/_functions.scss | sassdoc -It makes it easy to debug a documented Sass file, especially when using it in combination with the --parse flag which prints the SassDoc data structure as JSON:
cat stylesheets/utils/_functions.scss | sassdoc --parse -You could even run it on a file that is not on your machine, using curl. For instance, with a file hosted on GitHub:
curl https://raw.githubusercontent.com/SassDoc/sassdoc-theme-default/master/scss/utils/_functions.scss | sassdoc --parse -Speaking of debugging, we introduced a --debug option to print information about the current setup such as SassDoc version, arguments, enabled options and everything. Especially useful when opening an issue on the repository: just put the trace printed by --debug.
» [DEBUG] argv: ["scss/","--debug"]
» [DEBUG] process.argv: ["node","/Users/admin/Documents/projects/sassdoc/sassdoc/bin/sassdoc","scss/","--debug"]
» [DEBUG] sassdoc version: 2.0.3
» [DEBUG] node version: 0.10.33
» [DEBUG] npm version: 2.1.9
» [DEBUG] platform: darwin
» [DEBUG] cwd: /Users/admin/Documents/projects/sassdoc/sassdoc-theme-default
» [DEBUG] env: {
"strict": false,
"file": ".sassdocrc",
"dest": "sassdoc",
"dir": "/Users/admin/Documents/projects/sassdoc/sassdoc-theme-default",
"package": {},
"themeName": "default",
"src": [
"scss/"
]
}
» [DEBUG] task: documentize
» [DEBUG] Dumping data to `sassdoc-data.json`.Better default theme
We also put a lot of love into the default theme to improve it as much as we can. One important feature we added is the ability for you to use Google Analytics or basically any other tracking system in your generated docs. To do so, we introduced two extra keys to the configuration: googleAnalytics and trackingCode.
The googleAnalytics property is simply a Google Analytics tracking key mapped to your site. The theme will print the relevant JavaScript snippet with your key so you can get GA tracking.
googleAnalytics: UA-XXXXX-YYAlong the same lines, the trackingCode option also helps putting some tracking system on your docs, except it’s a bit more permissive. Basically, it’s some HTML that gets printed right before closing the tag. Beware to what you put in there, of course.
trackingCode: |
<img src="http://piwik.example.org/piwik.php?idsite={$IDSITE}amp;rec=1" style="border:0" alt="" />What’s next?
We have frozen SassDoc’s feature set weeks before launching version 2 in order to focus on refactoring everything without having new developments getting in the way. Now that Shiny Streamy Octopus is out, we can go back to implementing new features and we have had a lot of suggestions in the meantime. Among others:
- Add ability to introduce the docs with a short to long excerpt (#256).
- Add ability to define several groups for a same item as well nested groups (#135).
- Add ability to override an item’s name with a
@nameannotation (#296). - Add ability to order items by
@accessrather than groups in the theme (#239). - Add an option to assume an item is private if it starts with a
_or a-(#340). - Autofill more things, such as default values (#304).
- Allow theme inheritance and sub-themes (#272).
I think we’ll see many more suggestions come in the next few weeks. Of course, we value feedback a lot so if you have anything to tell, please be sure to do so.
Though allow me to take this article as an opportunity to state that SassDoc is still not planning on becoming a full-front documentation system. In that way, SassDoc cannot document CSS selectors and we are not planning on adding this feature any time soon (understand v3, perhaps).
SassDoc intends to document Sass API and projects. We are doing this single thing, but we are trying really hard to do it right. I think we still have plenty of progress to make on that field before going on to such a large thing like CSS selectors.
Anyway, be sure to have a look at the changelog for version 2 and the official site to read the documentation. Of course, we are available to answer any of your question on Twitter; just ping @SassDoc_ or myself!
Kitty GiraudelNon-binary trans accessibility & diversity advocate, frontend developer, author. Real life cat. She/they.
