sassdoc - npm Package Compare versions

Comparing version 1.9.0 to 1.10.0

CHANGELOG.md

 # Changelog
 
+## 1.10.0
+
+* Made annotations `@throws`, `@requires` and `@content` fill themselves so you don't have to, unless told otherwise through the [`autofill` option](http://sassdoc.com/configuration/#autofill) ([#232](https://github.com/SassDoc/sassdoc/issues/232), [#238](https://github.com/SassDoc/sassdoc/issues/238))
+* Added the ability to define `--sass-convert`, `--no-update-identifier` and `--no-prompt` options within the configuration file instead of CLI only ([#247](https://github.com/SassDoc/sassdoc/issues/247))
+* Merged [sassdoc-filter](https://github.com/sassdoc/sassdoc-filter) and [sassdoc-indexer](https://github.com/sassdoc/sassdoc-indexer) into [sassdoc-extras](https://github.com/sassdoc/sassdoc-extras); theme authors are asked to use the new repository
+
 ## 1.9.0
@@ -4,0 +10,0 @@

CONTRIBUTING.md

@@ -29,4 +29,3 @@ # Contributing
 * [Theme](https://github.com/sassdoc/sassdoc-theme-light): Theme, templates and styles
-* [Filter](https://github.com/sassdoc/sassdoc-filter): Markdown, display, groups...
-* [Indexer](https://github.com/sassdoc/sassdoc-indexer): Data structure
+* [Extras](https://github.com/sassdoc/sassdoc-extras): Extra tools for theme authors
 * [Grunt plugin](https://github.com/sassdoc/grunt-sassdoc): Grunt integration
@@ -33,0 +32,0 @@ * [Gulp plugin](https://github.com/sassdoc/gulp-sassdoc): Gulp integration

package.json

@@ -20,3 +20,3 @@ {
   ],
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": {
@@ -46,3 +46,3 @@ "type": "MIT",
     "chalk": "^0.5.0",
-    "docopt": "^0.4.0",
+    "fdocopt": "0.*",
     "js-yaml": "^3.2.1",
@@ -53,4 +53,5 @@ "lodash": "^2.4.1",
     "rimraf": "~2.2.8",
+    "safe-wipe": "0.*",
     "sassdoc-theme-default": "^1.6.0",
-    "scss-comment-parser": "0.4.*",
+    "scss-comment-parser": "^0.5.0",
     "semver": "^3.0.1",
@@ -57,0 +58,0 @@ "semver-regex": "^1.0.0",

README.md

@@ -22,3 +22,3 @@ # SassDoc
 
-[SassDoc](http://github.com/sassdoc/sassdoc) parses your source folder to grab documentation-specific comments. From there, it builds a data tree, that gets [enhanced](http://github.com/sassdoc/sassdoc-indexer) and [filtered](http://github.com/sassdoc/sassdoc-filter) before being passed to the [view](http://github.com/sassdoc/sassdoc-theme-light). So you end up with a fully styled HTML document located at your destination folder.
+[SassDoc](http://github.com/sassdoc/sassdoc) parses your source folder to grab [documentation-specific comments](/annotations/). From there, it builds a [data tree](/data-interface/), that gets [enhanced and filtered](/extra-tools/) before being passed to the [view](/customising-the-view/). So you end up with a fully styled HTML document located at your destination folder.
 
@@ -28,3 +28,4 @@ ## Getting started
 * [Getting Started](http://sassdoc.com/getting-started/)
-* [Documenting Your Items](http://sassdoc.com/documenting-your-items/)
+* [Configuration](http://sassdoc.com/configuration/)
+* [Annotations](http://sassdoc.com/annotations/)
 * [File-level Annotations](http://sassdoc.com/file-level-annotations/)
@@ -36,6 +37,7 @@ * [Customising The View](http://sassdoc.com/customising-the-view/)
 * [Using Your Own Theme](http://sassdoc.com/using-your-own-theme/)
-* [Theme Context](http://sassdoc.com/theme-context/)
+* [Data Interface](http://sassdoc.com/data-interface/)
 * [Extending SassDoc](http://sassdoc.com/extending-sassdoc/)
-* [Data Interface](http://sassdoc.com/data-interface/)
+* [Extra Tools](http://sassdoc.com/extra-tools/)
 * [Theme Generator](http://sassdoc.com/theme-generator/)
+* [Theme Gallery](http://sassdoc.com/theme-gallery/)
 
@@ -51,2 +53,3 @@ ## Alternative usages
 
+* [Changelog](http://sassdoc.com/changelog/)
 * [About](http://sassdoc.com/about/)
@@ -53,0 +56,0 @@ * [Frequently Asked Questions](http://sassdoc.com/frequently-asked-questions/)

src/annotation/annotations/access.js

@@ -8,4 +8,4 @@ 'use strict';
   default: function () {
-    return 'public';
+    return ['public'];
   }
 };

src/annotation/annotations/content.js

 'use strict';
 
-var utils = require('../../utils');
 module.exports = {
@@ -13,13 +12,8 @@
 
-  resolve: function(byTypeAndName){
-    utils.eachItem(byTypeAndName, function (item) {
-      if (!utils.isset(item.content) &&
-           utils.isset(item.context.code)){
-        if (item.context.code.indexOf('@content') > -1){
-          item.content = [{
-            autogenerated : true
-          }];
-        }
-      }
-    });
+  default : function(item){
+    if (item.context.code.indexOf('@content') > -1){
+     return [{
+       autogenerated : true
+     }];
+    }
   },
@@ -26,0 +20,0 @@

src/annotation/annotations/group.js

@@ -8,4 +8,4 @@ 'use strict';
   default: function () {
-    return ['undefined'];
+    return [['undefined']];
   }
 };

src/annotation/annotations/requires.js

@@ -7,3 +7,35 @@ 'use strict';
 var logger = require('../../log');
+var uniq = require('lodash').uniq;
 
+
+var searchForMatches = function(code, regex, index){
+  var match;
+  var matches = [];
+  while ( (match = regex.exec(code)) ) {
+    matches.push(match[index || 1]);
+  }
+  return uniq(matches);
+};
+
+
+var typeNameObject = function(type){
+  return function(name){
+    return {
+      type : type,
+      name : name,
+      autofill : true
+    };
+  };
+};
+
+var compareBefore = function(code, str, index){
+  for (var i=index-str.length,b=0;i<index;i++){
+    if (code[i] !== str[b]){
+      return false;
+    }
+    b++;
+  }
+  return true;
+};
+
 module.exports = {
@@ -42,4 +74,49 @@
 
+  autofill: function(item){
+    var type = item.context.type;
+    if (type === 'mixin' || type === 'placeholder' || type === 'function') {
+
+      // Searching for mixins and functions
+      var mixins = [];
+      var functions = [];
+      var mixinFunctionRegex = /\s*([\w\d_-]*)\(/g;
+      var match;
+      while ( (match = mixinFunctionRegex.exec(item.context.code)) ){
+        // Try if this is a mixin or function
+        if (compareBefore(item.context.code, '@include', match.index)){
+          mixins.push(match[1]);
+        } else {
+          functions.push(match[1]);
+        }
+      }
+
+      var placeholders = searchForMatches(item.context.code, /@extend\s+%([^;\s]+)/ig);
+      var variables    = searchForMatches(item.context.code, /\$([a-z0-9_-]+)/ig);
+
+      // Create object for each required item.
+      mixins       = mixins.map(typeNameObject('mixin'));
+      functions    = functions.map(typeNameObject('function'));
+      placeholders = placeholders.map(typeNameObject('placeholder'));
+      variables    = variables.map(typeNameObject('variable'));
+
+
+      // Merge all arrays
+      var all = [];
+          all = all.concat(mixins);
+          all = all.concat(functions);
+          all = all.concat(placeholders);
+          all = all.concat(variables);
+
+      // Merge in user supplyed requires if there are any
+      if (item.requires && item.requires.length > 0){
+        all = all.concat(item.requires);
+      }
+
+      if (all.length > 0){
+        return all;
+      }
+    }
+  },
+
   resolve: function (byTypeAndName) {
-
     utils.eachItem(byTypeAndName, function (item) {
@@ -72,3 +149,3 @@ if (utils.isset(item.requires)) {
           }
-          else {
+          else if (req.autofill !== true) {
             logger.log('Item `' + item.context.name +
@@ -75,0 +152,0 @@ '` requires `' + req.name + '` from type `' + req.type +

src/annotation/annotations/throws.js

 'use strict';
 
+var autoParserError = /@error\s+(?:'|")([^'"]+)/g;
+
 module.exports = {
@@ -7,3 +9,14 @@ parse: function (text) {
   },
-  alias: ['throw', 'exception']
+  autofill: function(item){
+    var match;
+    var throwing = item['throws'] || [];
+    while ( (match = autoParserError.exec(item.context.code)) ) {
+      throwing.push(match[1]);
+    }
+    if (throwing.length > 0) {
+      return throwing;
+    }
+  },
+  alias: ['throw', 'exception'],
+  allowedOn: ['function', 'mixin', 'placeholder']
 };

src/api.js

@@ -6,2 +6,3 @@ 'use strict';
 var cgf = require('./cfg');
+var safeWipe = require('safe-wipe');
 
@@ -30,6 +31,18 @@ exports = module.exports = {
 
-    return fs.folder.refresh(destination)
+    return safeWipe(destination, {
+      interactive: config.interactive || false,
+      parent: source,
+      silent: true,
+      force: config.force
+    })
       .then(function () {
+        return fs.folder.create(destination);
+      }, function (err) {
+        logger.error(err.message);
+        err.silent = true;
+        throw err;
+      })
+      .then(function () {
         logger.log('Folder `' + destination + '` successfully generated.');
-        return fs.getData(source, config.theme.annotations);
+        return fs.getData(source, config.theme.annotations, config.view);
       })
@@ -57,3 +70,5 @@ .then(function (data) {
       }, function (err) {
-        logger.error('stack' in err ? err.stack : err);
+        if (!err.silent) {
+          logger.error('stack' in err ? err.stack : err);
+        }
         throw err;
@@ -70,4 +85,4 @@ });
    */
-  parse: function (source) {
-    return fs.getData(source);
+  parse: function (source, annotations, view) {
+    return fs.getData(source, annotations, view);
   },
@@ -74,0 +89,0 @@

src/file.js

@@ -5,3 +5,2 @@ 'use strict';
 var mkdirp = require('mkdirp');  // mkdir -p
-var rimraf = require('rimraf');  // rm -rf
 var Q = require('q');            // Promises
@@ -42,23 +41,2 @@ var path = require('path');      // Path
     /**
-     * Remove a folder.
-     * @see {@link https://github.com/isaacs/rimraf}
-     * @see {@link https://github.com/kriskowal/q/wiki/API-Reference#interfacing-with-nodejs-callbacks}
-     */
-    remove: Q.denodeify(rimraf),
-
-    /**
-     * Remove then create a folder.
-     * @param  {String} folder
-     * @return {Q.Promise}
-     */
-    refresh: function (folder) {
-      return exports.folder.remove(folder).then(function () {
-        logger.log('Folder `' + folder + '` successfully removed.');
-        return exports.folder.create(folder);
-      }, function () {
-        return exports.folder.create(folder);
-      });
-    },
-
-    /**
      * Parse a folder.
@@ -159,5 +137,6 @@ * @param  {String} folder
    * @param {Array} annotations - Additional annotations to use
+   * @param {Object} view - view configuration
    */
-  getData: function (folder, annotations) {
-    var parser = new Parser();
+  getData: function (folder, annotations, view) {
+    var parser = new Parser(view);
         parser.annotations.addAnnotations(annotations);
@@ -164,0 +143,0 @@

src/parser.js

@@ -8,5 +8,5 @@ 'use strict';
 
-var Parser = function(){
+var Parser = function(config){
   this.annotations = new AnnotationApi();
-  this.scssParser = new ScssCommentParser(this.annotations.list);
+  this.scssParser = new ScssCommentParser(this.annotations.list, config);
 
@@ -13,0 +13,0 @@ this.scssParser.commentParser.on('warning', function (warning) {

No alert changes

Improved metrics

Number of lines in readme file

62

increased by5.08%

Number of low supply chain risk alerts

5

decreased by-16.67%

Worsened metrics

Total package byte prevSize

713947

decreased by-1.08%

Dependency count

14

increased by7.69%

Number of package files

59

decreased by-3.28%

Lines of code

2740

decreased by-2.21%

Dependency changes

• + Addedfdocopt@0.*

• + Addedsafe-wipe@0.*

• + Addedcdocparser@0.4.0(transitive)

• + Addeddocopt@0.6.2(transitive)

• + Addedextend@3.0.2(transitive)

• + Addedfdocopt@0.1.3(transitive)

• + Addedsafe-wipe@0.2.5(transitive)

• + Addedscss-comment-parser@0.5.0(transitive)

• - Removeddocopt@^0.4.0

• - Removedcdocparser@0.3.8(transitive)

• - Removeddocopt@0.4.1(transitive)

• - Removedscss-comment-parser@0.4.0(transitive)

• Updatedscss-comment-parser@^0.5.0