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 Issues

Support multi-line example code descriptions

Create a build process and integrate Travis CI

Add 100% unit test coverage

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

);

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 multiple example annotations in one comment block

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

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.

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.

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

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.

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.

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:

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

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

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

The tabs and spaces get stripped out.

optimizely / scribesass-parser Goto Github PK

scribesass-parser's Issues

Recommend Projects

Recommend Topics

Recommend Org