Commit beba889e authored by Björn Bartels's avatar Björn Bartels

updated help/docs

parent 2b3223db
Pipeline #59 passed with stage
This diff is collapsed.
## *Patternlibrary* API Reference
This section is about using the *Patternlibrary* API.
...
## *Patternlibrary* GUI front-end reference
This section is about using the *Patternlibrary* GUI front-end.
...
## *Patternlibrary* middleware Reference
This section is about using the *Patternlibrary* server middleware.
...
## 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.
This diff is collapsed.
## 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.
...
## 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.
# (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.
---
This diff is collapsed.
......@@ -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