Ability to generate documentation through Sassdoc or similar tool

[elussich]

I was trying to use Sassdoc along bem-constructor but then I realized that Sassdoc only works for certain Sass items (variables, functions, mixins and placeholders).

Thing is, most of the times (if not 100% of them) I find myself defining different blocks, objects or components by starting with the @include operator, which is certainly not caught by Sassdoc. That means all of my potential nice and clean documentation for that given block or component will just not be parsed and rendered by that tool.

I wonder if there is any chance to investigate on this, whether it is a way to integrate Sassdoc or any other similar tool into your library, or come up with a built-in alternative to produce docs from the blocks created.

Thanks for your time, this is an awesome library.

[danielguillan]

Thanks @elussich!

I use Sassdoc in most of my projects to document variables, functions and mixins but not the output of those. I'll take a look and see what we can be done. Please feel free to share any ideas you may have.

[elussich]

Hi Daniel, thanks for your response.

I tried to get my head around SassDoc to fit our documentation purposes, but as they put it in the first place, SassDoc is a documentation tool for Sass code, not for a CSS system (i.e. some BEM/OOCSS, SMACSS construction).
Here are some links providing more insight on that matter:
SassDoc/sassdoc#18
SassDoc/sassdoc#309

What I've tried (in a very clumsy way) was defining my BEM blocks inside a mixin, which will be immediately executed on the same file. Something along these lines:

/**
 * @name Navbar Component
 * @description The Navbar Component Description
 */
@mixin navbarComponent() {
  @include component('navbar') {
    background-color: #ccc;

    @include element('title') {
      color: #f00;
    }
  }
}
@include navbarComponent;

This would indeed be correctly parsed by SassDoc, but the resulting documentation will still be referenced as a mixin, not as a special entity such a block, component, or else, which, I believe, it is the main goal behind all this.

I also saw SassDocJs as a very suitable alternative, it looks very promising, but unfortunately, I haven't been able to run it on my machine due to some compilation errors (shame on me... I already contacted SassDocJs on that matter anyway).

Another possible alternative would be to work on a "built-in" documentation system for your own bem-constructor library, although it sounds a little too overkill, and at the same time, I think one of the nicest thing of your library was the freedom it provides in terms of how you organize your code and which methodologies the developer would incorporate, so enforcing a given type of documentation structure may not be the direction to go.

Let me know your thoughts on all this. I'll be more than happy to help.
Cheers!