optimizely / scribesass-parser Goto Github PK

View Code? Open in Web Editor NEW

3.0 105.0 2.0 65 KB

Automatically generate documentation for Sass files.

JavaScript 97.28% CSS 2.72%

scribesass-parser's Introduction

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 People

Contributors

Stargazers

Watchers

Forkers

isabella232

scribesass-parser's Issues

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.

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.

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.

Support multiple example annotations in one comment block

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

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);

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);
  }
}

Support multi-line example code descriptions

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.

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.

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.

Create a build process and integrate Travis CI

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

The tabs and spaces get stripped out.

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;
}

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)
  )

);

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);
}

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.