Open elussich opened 8 years ago
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.
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:
https://github.com/SassDoc/sassdoc/issues/18
https://github.com/SassDoc/sassdoc/issues/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!
I was trying to use
Sassdoc
alongbem-constructor
but then I realized thatSassdoc
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 bySassdoc
. 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.