add/update docs, update tests, update package config, clean up

docs/options_docs.md

+## Options
+
+For a reference of all options applied, you can also take a look at the `lib/config/defaults.js` file inside **Patternlibrary**'s source/module folder.
+
+
+### Basics
+
+This basic set of options is similar to the one set for the 'Panini' module used by the 'Zurb Foundation' project.
+
+- #### `dest`
+
+  **Type:** `String`
+
+  Set the destination path where to put the generated files.   
+  **mandatory**
+
+
+- #### `partials`
+
+  **Type:** `String`
+
+  Set the 'partials' source path. Your patterns should bo found in there or it's sub-folders.   
+  _optional_, default: `src/patterns`
+
+
+- #### `root`
+
+  **Type:** `String`
+
+  Set the "root" 'pages' source path.   
+  _optional_, default: `src/pages`
+
+
+- #### `layouts`
+
+  **Type:** `String`
+
+  Set the 'layouts' source path.   
+  _optional_, default: `src/layouts`
+
+
+- #### `data`
+
+  **Type:** `String`
+
+  Set the path from where to read JSON or YAML data files   
+  _optional_, default: `src/data`
+
+
+- - - - - - - - - - - - - - - - - - - - - - - -
+
+
+### Special options
+
+
+- #### `verbose`
+
+  **Type:** `Boolean`
+
+  Create verbose console output.   
+  _optional_, default: false
+  
+
+- #### `patterns`
+
+  **Type:** `Object`
+
+  Set the pattern specific sub-paths relative to the `partials` path.  
+  _optional_, default: 
+  ```js
+{
+    atoms     : 'atoms/',
+    molecules : 'molecules/',
+    organisms : 'organisms/',
+    templates : 'tempates/'
+}
+  ```
+
+
+- #### `patternfilenames`
+
+  **Type:** `Object`
+
+  Set the pattern specific file-name patterns.   
+  _optional_, default: 
+  ```js
+{
+    'main'       : '{index,pattern}.{html,hbs,handlebars}',
+    'readme'     : '{readme,info}.{md,markdown}',
+    'markup'     : '{example,examples}.{md,markdown}',
+    'javascript' : '{index,module}.js',
+    'scss'       : '{style,styles,pattern}.{scss,sass,css}',
+    'tests'      : '{test,tests,visual,visualtest,visualtests}.js',
+    'changelog'  : 'changelog.{md,markdown}'
+}
+  ```
+
+
+- #### `patternsearchpath`
+
+  **Type:** `String`
+  
+  Set the sub-path search-pattern under 'partials'-path to find the patterns.
+  _optional_, default: '*/**/',
+    
+
+- #### `templates`
+
+  **Type:** `Object`
+  
+  Set template files and template options
+  ```js
+    {
+        // Patternlibrary helpers path
+        'helpers'          : 'helpers/',
+        
+        // Patternlibrary layout file
+        'layout'           : 'patternlibrary',
+          
+        
+        // Patternlibrary partials templates
+        //
+
+        // Patternlibrary main page template
+        'page'             : 'patternlibrary',
+        
+        // main index page template
+        'mainindex'        : 'templates/index.html',
+        
+        // pattern list template
+        'patternlist'      : 'templates/patternlist.html',
+        // pattern display template
+        'patterndisplay'   : 'templates/patterndisplay.html', 
+ 
+        // pattern main index page template
+        'patternindex'     : 'templates/pattern-index.html', 
+        // pattern readme display template
+        'patternreadme'    : 'templates/patterndisplay-readme.html', 
+        // pattern markup display template
+        'patternmarkup'    : 'templates/patterndisplay-markup.html', 
+        // pattern javascript display template
+        'patternjavascript': 'templates/patterndisplay-javascript.html', 
+        // pattern scss display template
+        'patternscss'      : 'templates/patterndisplay-scss.html', 
+        // pattern template-file display template
+        'patterntemplate'  : 'templates/patterndisplay-template.html', 
+        // pattern tests display template
+        'patterntests'     : 'templates/patterndisplay-tests.html', 
+        // pattern changelog display template
+        'patternchangelog' : 'templates/patterndisplay-changelog.html', 
+        
+        // page list template
+        'pagelist'         : 'templates/pagelist.html',
+        // page display template
+        'pagedisplay'      : 'templates/pagedisplay.html' 
+    }
+  ```
+
+
+- - - - - - - - - - - - - - - - - - - - - - - -
+
+
+### Plug-in options
+
+
+- #### `plugins`
+
+  **Type:** `Object`
+
+  - `docparser`
+
+      **Type:** `Object`
+
+      Set special 'DocParser' options
+      _optional_
+
+  - `docrenderer`
+
+      **Type:** `Object`
+
+      Set special 'DocRenderer' options
+      _optional_
+
+  - `filestream`
+
+      **Type:** `Object`
+
+      Set special 'filestream' options
+      _optional_
+
+  - `middleware`
+
+      **Type:** `Object`
+
+      Set special 'middleware' options
+      _optional_
+
+
+
+- - - - - - - - - - - - - - - - - - - - - - - -
+
+
+### Sub-modules' options
+
+You can also set some module specific options.   
+**But use them with caution!** They strongly influence **Patternlibrary**'s functionality. 
+Some really critical options are overruled by hard-coded settings.
+
+- #### `handlebars`
+
+  **Type:** `Object`
+
+  Set 'handlebars' options.
+
+- #### `panini`
+
+  **Type:** `Object`
+
+  Set 'panini' options.
+
+- #### `supercollider`
+
+  **Type:** `Object`
+
+  Set 'supercollider' options.
+
+- #### `marked`
+
+  **Type:** `Object`
+
+  Set 'marked' options.
+
+- #### `sassdoc`
+
+  **Type:** `Object`
+
+  Set 'sassdoc' options.
+
+- #### `jsdoc`
+
+  **Type:** `Object`
+
+  Set 'jsdoc' options.
+
+
+

docs/patternspecs_docs.md

+# Generating the library and pattern documentation
+
+
+## Pattern files and folders
+
+For automatic generation of the *Patternlibrary* the pattern templates will have to be set up according to a simple folder and file structure.
+
+The main folders are:
+```
+{partials-dir}/
+   |
+   |- atoms/
+   |- molecules/
+   |- organisms/
+```
+
+The pattern files are stored in the pattern's type sub-folder:
+```
+{partials-dir}/
+   |
+   |- {type}/
+     |- {patternname}/
+```
+Multiple patterns can be grouped in intermediate sub-folders:
+```
+{partials-dir}/
+   |
+   |- {type}/
+     |- {group}/
+       |- {patternname}/
+```
+When including a pattern inside pattern templates ( `{{> "..."}}` or `{{PL ...}}` ), the pattern can be referenced by its structural item path `{{> "{type}/{group}/{patternname}"}` or using the *Patternlibrary* helper `{{PL {type}="{group}/{patternname}"}`.
+
+Example folder structure:
+```
+{partials-dir}/
+   |
+   |- atoms/
+   |  |- link/
+   |  |- nav/
+   |    |- link/
+   |   ...
+   |
+   |- molecules/
+      |- nav/
+        |- topbar/
+          |- navitem/
+        |- sub/
+          |- navitem/
+
+  . . .
+```
+
+The pattern files are stored inside the pattern's sub-folder.
+Mandatory is, of course, the pattern's template file...
+```
+{partials-dir}/
+   |
+   |- {type}/
+     |- {group}/
+       |- {patternname}/
+         - 'index.html'
+```
+ To provide more detailed information you may include
+```  
+         - 'readme.md' = a description, examples...
+         - 'changelog.md' = log file of changes
+```  
+The main CSS/SASS file is
+```  
+         - 'styles.scss'
+```
+The main JavaScript file is
+```  
+         - 'index.js' or 'module.js'
+```  
+You can also provide test files, optionally grouped inside a sub-folder 
+```  
+          - test/
+             - 'test.js'
+```  
+
+Example pattern files structure:
+```
+{partials-dir}/
+   |
+   |- atoms/
+   |  |- nav/
+   |    |- link/
+   |      - 'index.html'
+   |      - 'styles.scss'
+   |      - 'readme.md'
+   |      - 'changelog.md'
+   |      - 'test.js'
+   |
+   |   ...
+   |
+  . . .
+  
+```
+
+
+
+Referencing when using the *handlebars* helper:
+```
+   {{> "atom/link"}}  and {{> "atom/nav/link"}}
+```
+...or using the *Patternlibrary* helper:
+```
+   {{PL atom="link"}}  and {{PL atom="nav/link"}}
+   
+   {{PL molecule="nav/topbar/navitem"}}  and {{PL molecule="nav/sub/navitem"}}
+```
+
+
+
+
+
+## Pattern specifications
+
+
+- ### `pattern`
+
+  The container object for patterns-specific meta-data
+
+  - #### `name`
+
+      **Type:** `String`
+
+      Name (and type) of the pattern, according to its structural item path in the form of `{type}/({group}/){patternname}`,  i.e.: `atom/link` or `atom/nav/link`
+     ! **mandatory**
+
+
+  - #### `categories`
+
+      **Type:** `[String]`
+
+      List of categories to apply to the pattern
+      _optional, default: []
+
+
+  - #### `uses`
+
+      **Type:** `[String]`
+
+      List of other patterns used, a.k.a. included, by the pattern
+      _optional, default: []
+
+
+- ### `params`
+
+  **Type:** `Object`
+
+  Set of pattern-specific parameters to apply to the pattern upon inclusion, i.e.:
+  ```html
+  {{> "mypattern" some_parameter="value"}}
+  ```
+  _optional_, default: {}
+
+
+- ### `defaults`
+
+  **Type:** `Object`
+
+  Set of values to apply to the pattern parameters if those are omitted upon inclusion. To function correctly, these object keys must match the keys of the `params` object.
+  _optional_, default: {}
+
+
+
+## Patternfile: readme.md
+
+...
+
+
+

docs/readme_docs.md

+## Patternfile: readme.md
+
+...
+

docs/sass_js_docs.md

+## SASS and JavaScript Reference
+
+
+This section is about creating reference and API documentation.
+...
+
+
+
+
+### Sourcecode documentation: SASS (SassDoc)
+
+
+This section is about creating SASS reference and/or API documentation.
+...
+
+
+
+
+
+### Sourcecode documentation: JavaScript (JSDoc) 
+
+
+This section is about creating JavaScript reference and/or API documentation.
+...
+
+
+
+
+

docs/testing_docs.md

+## Testing
+
+
+This section is about sourcecode and component testing procedures.
+...
+
+
+
+### Writing tests
+
+
+This section is about writing tests.
+...
+
+
+
+#### Unit tests
+
+
+This section is about writing unit tests.
+...
+
+
+##### SASS
+
+
+This section is about writing SAS unit tests.
+...
+
+
+
+##### JavaScript
+
+
+This section is about writing JS unit tests.
+...
+
+
+
+
+
+#### Visual tests
+
+
+This section is about writing visual tests.
+...
+
+
+
+
+### Running the tests
+
+
+This section is about running the tests.
+...
+
+
+
+

docs/usage_docs.md

+## Installation
+
+For now, just add 
+```js
+"patternlibrary": "git+https://gitlab.bjoernbartels.earth/js/patternlibrary.git"
+```
+to your `package.json` file.
+
+Once the stable release has arrived, install via npm
+
+```bash
+$> npm install patternlibrary --save-dev
+```
+
+
+## Gulp usage
+
+You can setup **Patternlibrary** in a gulp task.    
+See the ['options' documentation page](options_docs.md) to see all options available.
+
+```js
+var gulp = require('gulp');
+var Patternlibrary = require('node-patternlibrary');
+
+/** @var Patternlibrary */
+var $PL = null;
+
+// initialize Patternlibrary task
+gulp.task('patternlibrary:init', function (done) {
+    
+    // initialize Patternlibrary
+    if (null == $PL) {
+        $PL = Patternlibrary({
+            verbose  : true,
+            dest     : 'dist/pl/',
+            basepath : '/pl',
+            partials : 'src/partials/'
+        });
+    }
+    
+    // finish task
+    done();
+    
+});
+
+// run Patternlibrary generation
+gulp.task('patternlibrary:run', function (done) {
+    
+    // generate Patternlibrary pages
+    if ($PL != null) {
+        // ...go, go $PL ! 
+        $PL.run();
+    }
+
+    // finish task
+    done();
+    
+});
+
+// refresh patternlibrary dist files and data
+gulp.task('patternlibrary:refresh', function (done) {
+    Patternlibrary.refresh();
+    done();
+});
+
+// preparations, clear dist-dir, 
+gulp.task('patternlibrary:prepare',
+    gulp.series(
+        'clean:patternlibrary-dist',
+        'copy:patternlibrary'
+    )
+);
+
+// main 'patternlibrary' task
+gulp.task('patternlibrary',
+    gulp.series(
+        'patternlibrary:prepare',
+        'patternlibrary:init',
+        'patternlibrary:run'
+    )
+);
+```
+
+Note that **Patternlibrary** loads the partials/patterns and data files once on first run, 
+also meta-data is gather from all the pattern templates.
+
+Whenever these files change, call the `Patternlibrary.refresh()` method to get it up to date.    
+You can easily do this inside a call to `gulp.watch()`:
+
+```js
+gulp.watch(['./src/partials/**/*'], ['patternlibrary:refresh']);
+```
+
+
+## Standalone module usage
+
+**Patternlibrary** is also usable as a standalone node module to integrate into your project. 
+
+```js
+var Patternlibrary = require('node-patternlibrary');
+
+// initialize Patternlibrary
+/** @var Patternlibrary */
+var $PL = Patternlibrary({
+    verbose  : true,
+    dest     : patternlibraryDestination,
+    basepath : '/pl',
+    partials : 'src/partials/'
+});
+
+// run Patternlibrary generation
+$PL.run();    
+```
+
+See the [API documentation page](api_docs.md) for a full overview of available methods.
+
+
+
+## CLI
+
+You can (_**currently not yet**_) use **Patternlibrary** via the CLI.
+
+```bash
+THIS IS SUBJECT TO CHANGE!  D O   N O T   U S E  ! ! !
+
+Usage: patternlibrary --partials=[partialsdir] --dist=[destdir] [other options...]
+
+Options:
+  --dist     (required) path to the folder compiled pages should get sent to
+  --partials            path to root folder for partials
+  ...
+
+Example: patternlibrary --partials=src/partials --dist=dist/pl/ ...
+```
+
+
+
+
+## Local Development
+
+If you like to contribute to/experiment with **Patternlibrary**, checkout the repo...
+```bash
+$> git clone https://gitlab.bjoernbartels.earth/js/patternlibrary node-patternlibrary
+$> cd node-patternlibrary
+$> npm install
+```
+
+...just add the local repo to your `package.json` file...
+```js
+    "node-patternlibrary": "file:../path/to/node-patternlibrary"
+```
+
+...and link the repo to your project via npm
+```bash
+$> cd projectname
+    
+$> npm link ../path/to/node-patternlibrary 
+```
+
+## Testing
+
+Simply, use `npm test` to run **Patternlibrary** tests.

package.json

@@ -40,9 +40,8 @@
     "kebab-case": "^1.0.0",
     "multiline": "^1.0.2",
     "string-template": "^1.0.0",
-    "strip-indent": "^1.0.1"
-  },
-  "devDependencies": {
+    "strip-indent": "^1.0.1",
+
     "assert-dir-equal": "^1.0.1",
     "babel": "^6.3.26",
     "babel-preset-es2015": "^6.3.13",
@@ -50,10 +49,10 @@
     "babel-runtime": "^6.3.19",
     "coveralls": "^2.11.6",
     "gulp": "^3.8.11",
-    "jsonfile": "^3.0.0",
     "mocha": "^3.2.0",
-    "mocha-lcov-reporter": "^1.0.0",
-    "vinyl-fs": "^2.3.1"
+    "mocha-lcov-reporter": "^1.0.0"
+  },
+  "devDependencies": {
   },
   "repository": {
     "type": "git",

readme.md

-# Pattern-library
+# (Node-)**Patternlibrary**
 
-A super simple flat file pattern-library generator for use with Gulp. It compiles a series of HTML **patterns** structred as in an **atomic desing pattern**. These patterns can also include HTML **partials**, external Handlebars **helpers**, or external **data** as JSON or YAML.
+[![Scrutinizer Code Quality](https://scrutinizer-ci.com/gl/bjoernbartels-earth/js/patternlibrary/badges/quality-score.png?b=master&s=974f5fcc342590b04f6b62f995f7f991ad6e32c7)](https://scrutinizer-ci.com/gl/bjoernbartels-earth/js/patternlibrary/?branch=master)
+[![Build Status](https://scrutinizer-ci.com/gl/bjoernbartels-earth/js/patternlibrary/badges/build.png?b=master&s=bcca11629f60424efbc35db6c110e4091a513681)](https://scrutinizer-ci.com/gl/bjoernbartels-earth/js/patternlibrary/build-status/master)
 
 
+## About
 
 
-## Installation
+**Patternlibrary** (a.k.a. _node-patternlibrary_) is a simple flat file documentaion generator for use with Node, Gulp or Grunt.   
+It compiles a series of HTML **patterns** (a.k.a. _partials_) structured in an **atomic desing pattern**. These patterns can also include other HTML **patterns**/**partials**, external Handlebars **helpers**, or external **data** as JSON or YAML.   
+Documentation pages for each pattern are created according to the specific pattern meta-data supplied. Those pages are combined under a GUI to view in your browser.
 
-For now, just add 
-```bash
 
-    "patternlibrary": "git+https://gitlab.bjoernbartels.earth/js/patternlibrary.git"
+## Documentation
 
-```
-to your `package.json` file.
 
+For detailed explanations of each of the parts that made up **Patternlibrary**, please see the following pages:
 
-During pattern-library development, just link the (local) repo to your project via npm
-```bash
+- [Installation and (basic) usage](docs/usage_docs.md)
 
-	$> cd projectname
-	
-    $> npm link ../path/to/patternlibrary
+- [Options](docs/options_docs.md)
 
-```
+- [Generating pattern documentation](docs/patternspecs_docs.md)
 
+  To generate the pattern-specific documentation pages, at least two requirements must be satisfied for each pattern:
 
+  - the [Pattern specifications](docs/patternspecs_docs.md)
+  
+  and...
+  
+  - the [`readme.md` file](docs/readme_docs.md)
+  
+  
+  Optionally, you can also apply...
+  
+  - [SASS reference documentation](docs/sassdoc_docs.md),
+  
+  - [JavaScript reference documentation](docs/jsdoc_docs.md),
+  
+  - a [`changelog.md` file](docs/changelog_docs.md) and