Add more Sassdoc annotations and generate Sass docs in markdown

Summary

We’re currently using Sassdoc to mark public or private @access but beyond that, we’re inconsistent and documenting Sass hasn’t been a priority.

Once https://github.com/IBM/carbon-elements/pull/462 is merged and subsequently merged into carbon-components, we can modify our build to auto-generate our public Sass API.

Here’s an example from carbon-elements once all Sass functions, mixins, and variables have been annotated: https://github.com/IBM/carbon-elements/blob/0f6ffed16a7aa0b3074a665ea7b54184a5bec7b6/packages/elements/docs/sass.md

There would be three parts to completing this:

1. Add complete, consistent, Sassdoc annotations to all Sass source originating from carbon-components
2. Document Sassdoc annotation style in our contribution guidelines
3. New build script to call in our built, e.g.:

"scripts": {
  "build": "gulp build && yarn docs",
  "docs": "bundler sassdoc 'scss' --output 'docs/api' && bundler sassdoc 'scss' --json --output 'docs/api/data'"
}

That example above generates sass.md in the /docs/api directory, and also sass.json in /docs/api/data directory. sass.json is the data dump generated by Sassdoc during the build.

Not in scope for this issue: Going forward, it would be great to have carbon-website consume the json object and render a more visually appealing way to understand and use our tokens.

Justification

Our Sass is minimally documented and even with the current comments, you have to crawl through source to find it.

By having one source of truth (/docs/api/sass.md), a developer can more easily find what’s available in our Sass API when using Carbon styling to extend Carbon through custom components or to theme Carbon.

Not in scope for this issue: Also, with /docs/api/data/sass.json, we’d be able to programmatically present token and theming information in carbon-website.

[asudoh]

OK cool - Thank you @mattrosno for clarifying!

[mattrosno]

@asudoh regarding carbon-website, that works.

This issue focuses on /docs/api/sass.md that lives in this repo.