optimizely / scribesass-parser

Automatically generate documentation for Sass files.

ScribeSass

Parse SCSS comments and return a JSON object.

Usage

Require scribesass-parser and provide it a path to a .scss file.

var scribeSass = require('scribesass-parser');

// Provide path to a file and receive an array of files containing `path` and `ast` properties.
scribeSass.create('main.scss', function(err, files) {
  // Get an object of group objects containing file objects.
  var groups = scribeSass.getGroups(files);

  // Loop through the files.
  for (var i = 0; i < files.length; i++) {
    // Path to the file.
    var path = files[i].path;

    // Get SCSS from an AST.
    var scss = scribeSass.getScss(files[i].ast);

    // Get object of file properties from AST.
    var fileProperties = scribeSass.getFileProperties(files[i].ast);

    // Get array of parsed comment objects and ASTs from AST.
    // ```js
    // comments = [{
    //   properties = {...},
    //   ast = {...},
    // }]
    // ```
    var comments = scribeSass.getComments(files[i].ast);
  }
});

scribesass-parser's Issues

Create a build process and integrate Travis CI

Link comments to source code

Currently the parsed comments don't know what block of code they are referring to.

This relates to issue #1.

Support multiple example annotations in one comment block

By default, only one will be supported. The JS should be modified to support multiple.

Add 100% unit test coverage

Provide function to remove ScribeSass formatted comments from AST

This can be used to display a version of the SCSS that doesn't have comments.

Support one comment for multiple items

This comment relates to all the classes below it. There should be a way to indicate this.

/// Flex classes

.flex {
  @include display(flex);
}

.flex-1 {
  @include flex(1);
}

.flex-none {
  @include flex(none);
}

.flex-wrap--wrap {
  @include flex-wrap(wrap);
}

Provide function to get an array of groups and the corresponding files.

Files can be grouped with the @group annotation, so it would be helpful to provide a function that returns an array groups and the corresponding file objects.

Proposal:

var scribeSass = require('scribesass-parser');

scribeSass.create('main.scss', function(files) {
  // Get an array of group objects containing files.
  var groups = scribeSass.getGroups(files);
});

groups would contain:

[
  {
    name: 'Objects',
    files: [
      {...},
      {...}
    ]
  }
]

File properties (name, for example) can be accessed by looping through the groups:

// Loop through the groups.
for (var i = 0; i < groups.length; i++) {
  var group = groups[i];

  for (var j = 0; j < group.files.length; j++) {
    var file = group.files[j];

    // Path to the file.
    var path = file.path;

    // Get object of file properties from AST.
    var fileProperties = scribeSass.getFileProperties(file.ast);
  }
}

Don't export the scss, but expose a function to allow user to convert AST to scss

Providing the Sass and AST seems like to much repetition.

Remove trailing whitespace from the end of ASTs

Some of the ASTs have newlines at the end that mess with the padding in the themes once converted to SCSS.

Show value of color and text variables

Compile the Sass and display the outputted color next to it.

$color: (

  ui: (
    white                    : $base-white,
    faint                    : map-fetch($root-color, grey-03),
    light                    : map-fetch($root-color, grey-06),
    base                     : map-fetch($root-color, grey-12),
    medium                   : map-fetch($root-color, grey-40),
    dark                     : map-fetch($root-color, grey-85),
    brand                    : map-fetch($root-color, brand),
    brand-light              : map-fetch($root-color, brand-light),
    brand-dark               : map-fetch($root-color, brand-dark),
    warning                  : map-fetch($root-color, warning),
    bad-news                 : map-fetch($root-color, bad-news),
    good-news                : map-fetch($root-color, good-news)
  ),

  link: (
    base                     : map-fetch($root-color, brand),
    brand-light              : map-fetch($root-color, brand-light),
    bad-news                 : map-fetch($root-color, bad-news),
    white                    : $base-white
  ),

  background: (
    base                     : $base-white,
    white                    : $base-white,
    faint                    : map-fetch($root-color, grey-03),
    light                    : map-fetch($root-color, grey-06),
    muted                    : map-fetch($root-color, grey-35),
    medium                   : map-fetch($root-color, grey-50),
    black                    : $base-black,
    brand                    : map-fetch($root-color, brand),
    brand-dark               : map-fetch($root-color, brand-dark),
    brand-light              : #F2F7FC,
    warning                  : #FCF8E3,
    bad-news                 : #F9E3E4,
    good-news                : #E9F6C3
  ),

  text: (
    base                     : map-fetch($root-color, grey-85),
    white                    : $base-white,
    faint                    : map-fetch($root-color, grey-12),
    light                    : map-fetch($root-color, grey-25),
    muted                    : map-fetch($root-color, grey-35),
    medium                   : map-fetch($root-color, grey-50),
    dark                     : map-fetch($root-color, grey-85),
    brand                    : map-fetch($root-color, brand),
    brand-dark               : map-fetch($root-color, brand-dark),
    warning                  : map-fetch($root-color, warning),
    bad-news                 : map-fetch($root-color, bad-news),
    good-news                : map-fetch($root-color, good-news)
  )

);

File and comment example code doesn't maintain tabs and spaces

The tabs and spaces get stripped out.

Clone the SCSS before deleting comments from it in `getScss`

This will actually modify the original AST instead of performing operations on a clone.

var scss = scribeSass.getScss(node.ast, true);

Parse code example annotations

The format is:

/// @example html - Image that has a standard border around it. 
/// <img src="http://fillmurray.com/100/100" class="img--border">

The JS should separate the language, description, and source.

Support multi-line example code descriptions

Comment name property for first comment fails if no file level comment

This would not return the name of the first annotation unless a file-level comment is added.

/// Compass polyfills
/// @description Line 1
/// Line 2!
.foo {
  color: red;
}

/// One more comment?
.bar {
  color: blue;
}

Fix extra space appearing above code examples

See screenshot:

Restrict annotations to the list of supported ones

Currently the user can define any annotation. This might be the case eventually but I'd like limit it for now.

Support @alias annotation

This would be used for searching through the output for keywords. For example, an "attention" bar object could be aliased to alert.