Evaluate SassDocs for use as possible documentation generation, as well as backstop regression testing.

[bnjmnrsh]

Having given sassdoc a go, I've found documenting all sass functions etc with sassdoc very compelling. The vscode plugin does some nice hinting and sassdocs own documentation is quite good and largely mimics JSDocs. I also like how easy it generates documentation on things like mixins, functions, maps etc, and has awesome search functionality baked in.

This said, the way sassdocs works means that out of the box, it doesn't appear to generate a static route for each unit or group (happy to be corrected here). With patternlab for example, in the generated documentation there is a ./styleguide/data/patternlab-data.js file that exports a whole host of data including routes to the static paths, which can be pretty handedly be fed to backstop.js. I don't see any equivalent behaviour for sassdocs.

Another hurdle is that sassdocs ecosystem is rather dormant at the moment, which is likely a byproduct of the lead developers have busy lives of their own and have moved on, a symptom of the maturity of the project that is largely feature complete, and/or the result of the community at large generally adopting tools other then Sass, or different documentation mechanisms.

EDIT see issue #555

Out of a team of four I'm more or less the last one trying to maintain at the very minimum the project (security fixes, reviewing and merging PRs, etc.). But some of those tasks takes time, especially merging PRs, major dep upgrades, as we need to make sure it doesn't break things. SassDoc 2 is pretty stable though, so it basically doesn't require a bunch of maintenance per se and can be used without worries.

Regardless, while I cannot justify two documentation mechanisms, I see little disadvantage to not adopting sassdoc for the inline docs of the project going forward.

[bnjmnrsh]

The documentation generator for sassdocs isn't quite as versatile as I would like, as much of our css is generated. One limitation is that @name isn't available from within generated css, while other features, like File Level Annotaions are. I am specifically interested in @name as it would appear help with the readability of documentation headings for output CSS. Consider this generated from a mixin:

////
/// @group Borders
/// @link http://tachyons.io/docs/themes/borders/
////

@include generate-breakpoints {
  /// border dotted
  /// @name `.b--dotted-[$bkpt-suffix]`
  .b--dotted#{$bkpt-suffix} {
    @include b--dotted;
  }
  ...
}

The results are not a great start for something like a functional lib like Tachyons.

While the above isn't entirely unexpected for Sass centric documentation, it isn't as readable as what Tachyons already has and doesn't appear flexible enough to come close to being able to generate it.

It is worth examining how much functionality can be imparted with a theme, and Herman also from OddBird seems to do just this.

OddBird has also created [Accoutrement] for 'Integrated design-system management in Sass'. It appears to be a suite of tools which help to process design tokens.

It may be worth also considering using a fork of scss-comment-parser to pump scss comments.

Interestingly both both PatternLab Docs and OddBird.net are built with 11ty

[bnjmnrsh]

There is also a lack of deep nesting within groups, which is limiting as we have lots of categorisation. See issue #135.

Variables and Maps don't have limited documentation mechanisms #389

Nested functions, mixins maps etc are difficult or impossible to document cleanly. https://github.com/SassDoc/sassdoc/issues/386 https://github.com/SassDoc/sassdoc/issues/111