Commit 476dff11 authored by Björn Bartels's avatar Björn Bartels

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

parent e468b8a7
Pipeline #21 passed with stage
This diff is collapsed.
## 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.
# 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
...
## Patternfile: readme.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.
...
## 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
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.
This diff is collapsed.
This diff is collapsed.
......@@ -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",
......
# 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