Skip to content

P
patternlibrary
Commit beba889e authored by Björn Bartels's avatar Björn Bartels
Browse files
Options

updated help/docs

parent 2b3223db
Pipeline #59 passed with stage
    Expand all Hide whitespace changes
    Inline Side-by-side
    Showing with 370 additions and 3231 deletions
    docs/all_in_one.md deleted 100644 → 0
    View file @ 2b3223db
    This diff is collapsed.
    docs/api_docs.md deleted 100644 → 0
    View file @ 2b3223db
    ## *Patternlibrary* API Reference
    This section is about using the *Patternlibrary* API.
    ...
    docs/gui_docs.md deleted 100644 → 0
    View file @ 2b3223db
    ## *Patternlibrary* GUI front-end reference
    This section is about using the *Patternlibrary* GUI front-end.
    ...
    docs/middleware_docs.md deleted 100644 → 0
    View file @ 2b3223db
    ## *Patternlibrary* middleware Reference
    This section is about using the *Patternlibrary* server middleware.
    ...
    docs/options_docs.md deleted 100644 → 0
    View file @ 2b3223db
    ## 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 deleted 100644 → 0
    View file @ 2b3223db
    This diff is collapsed.
    docs/testing_docs.md deleted 100644 → 0
    View file @ 2b3223db
    ## 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 deleted 100644 → 0
    View file @ 2b3223db
    ## Installation
    Just add and install via npm
    ```bash
    $> npm install node-patternlibrary --save
    ```
    You can also manually add
    ```js
    "node-patternlibrary": "^0.0.1"
    ```
    to your `package.json` file and run
    ```js
    $> npm update
    ```
    ## 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/patterns/',
    helpers : 'src/helpers/',
    layouts : 'src/layouts/',
    root : 'src/pages/',
    data : 'src/data/'
    });
    }
    // 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 : 'dist/pl/',
    basepath : '/pl',
    partials : 'src/partials/',
    helpers : 'src/helpers/',
    layouts : 'src/layouts/',
    root : 'src/pages/',
    data : 'src/data/'
    });
    // 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/ ...
    ```
    ## 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
    ```
    ### Bleeding edge
    If you like to try the to the minute up-to-date progress you can add one of the source repositories directly to your `package.json` file.
    - from our [GitLab](https://gitlab.bjoernbartels.earth/js/patternlibrary):
    `"node-patternlibrary": "git+https://gitlab.bjoernbartels.earth/js/patternlibrary.git"`
    - from [GitHub](https://github.com/bb-drummer/node-patternlibrary):
    `"node-patternlibrary": "git+https://github.com/bb-drummer/node-patternlibrary.git"`
    ### Testing
    In your local repository, simply use `npm test` to run **Patternlibrary** tests.
    gui/src/pages/index.md
    View file @ beba889e
    # (Node-)**Patternlibrary**
    # **Patternlibrary**
    [![npm version](https://badge.fury.io/js/node-patternlibrary.svg)](https://badge.fury.io/js/node-patternlibrary)
    [![dependencies status](https://david-dm.org/bb-drummer/node-patternlibrary.svg)](https://david-dm.org/bb-drummer/node-patternlibrary)
    [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/?branch=master)
    [![Build Status](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/badges/build.png?b=master)](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/build-status/master)
    [![npm version](https://badge.fury.io/js/node-patternlibrary.svg)](https://badge.fury.io/js/node-patternlibrary "npm version")
    [![dependencies status](https://david-dm.org/bb-drummer/node-patternlibrary.svg)](https://david-dm.org/bb-drummer/node-patternlibrary "dependencies status")
    [![Scrutinizer-CI code quality score](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/?branch=master "Scrutinizer-CI code quality score")
    [![Scrutinizer-CI build status](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/badges/build.png?b=master)](https://scrutinizer-ci.com/g/bb-drummer/node-patternlibrary/build-status/master "Scrutinizer-CI build status")
    [![Travis-CI build status](https://travis-ci.org/bb-drummer/node-patternlibrary.svg?branch=master)](https://travis-ci.org/bb-drummer/node-patternlibrary "Travis-CI build status")
    [![Build Status](https://travis-ci.org/bb-drummer/node-patternlibrary.svg?branch=master)](https://travis-ci.org/bb-drummer/node-patternlibrary)
    ### Work-In-Progress disclaimer
    This project is now still a work in progress!
    Some of its features and options are or may be a subject to change!
    ---
    DO NOT USE IN PRODUCTION ENVIRONMENTS !
    When using this software, absolutely no warranties of any sort are granted. Please see the license file for more information.
    ---
    ## Welcome to the self-documenting demo
    [[TOC]]
    ---
    ## About
    **Patternlibrary** (@ npm: _node-patternlibrary_) is a static site and pattern/component documentation generator for use with Node, Gulp or Grunt.
    It compiles a series of HTML **patterns**, or _partials_, or _components_, structured in an **atomic desing pattern**. These patterns can also include other **patterns**, external Handlebars **helpers**, or external **data** as JSON or YAML.
    **Patternlibrary** (a.k.a. _node-patternlibrary_) is a static site and pattern documentaion generator for use with Node, Gulp or Grunt.
    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.
    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.
    The GUI provides an overview dashboard, lists to browse patterns and categories and (kind of) interactive pattern documentation.
    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.
    The template engine used is [*Handlebars*](http://handlebarsjs.com) and rendering _markdown_ is accomplished with [*MarkdownIt*](https://github.com/markdown-it/markdown-it). Parsing the style and script source files is utilizing ([*SassDoc*](http://sassdoc.com/)) and ([*JSDoc*](http://usejsdoc.org)).
    The template engine used is *handlebars* ([-> homepage](http://handlebarsjs.com)) which itself is extended by *Zurb Foundation*'s *Panini* ([-> GitHub](https://github.com/zurb/panini)). The style and script source files are parsed by *Zurb Foundation*'s *Supercollider* ([-> GitHub](https://github.com/zurb/supercollider)) utilizing *SassDoc* ([-> homepage](http://sassdoc.com/)) and *JSDoc* ([-> homepage](http://usejsdoc.org)).
    ## Documentation
    For detailed explanations of each of the parts that made up **Patternlibrary**, please see the following pages:
    - [Installation and (basic) usage](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/usage_docs.md)
    For detailed explanations on how to use **Patternlibrary**, please see the browse the [help pages](./pl/help/docs/).
    - [Options](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/options_docs.md)
    - [Generating pattern documentation](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/patternspecs_docs.md)
    To generate the pattern-specific documentation pages, some requirements must be satisfied for each pattern:
    ## Example project
    - the [Pattern specifications](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/patternspecs_docs.md)
    and...
    - a [`readme.md` file](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/patternspecs_docs.md)
    Optionally, you can also apply...
    - [SASS reference documentation](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/sassdoc_docs.md),
    - [JavaScript reference documentation](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/jsdoc_docs.md),
    - a [`changelog.md` file](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/changelog_docs.md) and
    - [Test files and testing](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/testing_docs.md)
    - [GUI usage](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/gui_docs.md)
    - [API documentation and advanced usage](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/api_docs.md)
    - [Gulp/Grunt middleware usage](https://gitlab.bjoernbartels.earth/js/patternlibrary/tree/master/docs/middleware_docs.md)
    [An example front-end/theme project](https://gitlab.bjoernbartels.earth//themes/node-patternlibrary-demo) can be found in our [GitLab](https://gitlab.bjoernbartels.earth//themes/node-patternlibrary-demo).
    ## Example project
    [An example front-end/theme project](https://gitlab.bjoernbartels.earth//themes/node-patternlibrary-demo) can be found in our [GitLab](https://gitlab.bjoernbartels.earth//themes/node-patternlibrary-demo).
    ---
    ### Work-In-Progress disclaimer
    This project is now going from some kind of *Proof Of Concept* to real implementation.
    Most of its features and behavour is fixed so far.
    DO NOT USE IN PRODUCTION ENVIRONMENTS YET!
    When using this software, absolutely no warranties of any sort are granted. Please see the license file for more information.
    ---
    Copyright (c) 2017, [bjoernbartels.earth]
    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
    ......@@ -89,3 +74,9 @@ The above copyright notice and this permission notice shall be included in all c
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    Please, see the license file for more information.
    ---
    gui/src/pages/pl/help/docs/index.md
    View file @ beba889e
    This diff is collapsed.
    gui/src/pages/pl/help/docs/options_docs.md → gui/src/pages/pl/help/docs/options.md
    View file @ beba889e
    ......@@ -2,6 +2,93 @@
    layout: patternlibrary
    ---
    # Patternlibrary - Options and configuration
    [[TOC]]
    ---
    ## Configuration
    on instanciation :
    ```js
    const PL = new Patternlibrary(options);
    ```
    with `config` method:
    ```js
    const PL = new Patternlibrary();
    // ...
    PL.config(options);
    ```
    on initialisation :
    ```js
    const PL = new Patternlibrary();
    // ...
    PL.run(options);
    ```
    section in `package.json` file:
    ```js
    {
    "name": "my-package",
    "version": "1.2.3",
    // ...
    "patternlibrary": {
    "root" : "src/pages",
    "partials": "src/components",
    // ...
    }
    }
    ```
    a separate `.patternlibrary.rc` file in your project root:
    ```js
    {
    "root" : "src/pages",
    "partials": "src/components",
    // ...
    }
    ```
    ---
    ## 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.
    ......@@ -51,12 +138,6 @@ This basic set of options is similar to the one set for the 'Panini' module used
    _optional_, default: `src/data`
    - - - - - - - - - - - - - - - - - - - - - - - -
    ### Special options
    - #### `verbose`
    **Type:** `Boolean`
    ......@@ -65,19 +146,26 @@ This basic set of options is similar to the one set for the 'Panini' module used
    _optional_, default: false
    - - - - - - - - - - - - - - - - - - - - - - - -
    ### Special options