Skip to content

Commit 104d489

Browse files
bmuenzenmeyerbmuenzenmeyer
committed
docs(core): update event and public API documentation
1 parent 983b9b0 commit 104d489

File tree

4 files changed

+224
-95
lines changed

4 files changed

+224
-95
lines changed

‎packages/core/docs/README.md

Lines changed: 126 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -10,32 +10,59 @@
1010

1111
``` javascript
1212
const config = require('./patternlab-config.json');
13-
const patternlab = require('patternlab-node')(config);
13+
const patternlab = require('@pattern-lab/core')(config);
1414
```
1515

16-
## Events
17-
18-
Pattern Lab emits numerous [events](./events.md).
19-
20-
## Functions
16+
<a name="patternlab"></a>
2117

18+
## `patternlab` : <code>object</code>
19+
Build thoughtful, pattern-driven user interfaces using atomic design principles.
2220
Many of these functions are exposed to users within [Editions](https://github.com/pattern-lab/patternlab-node#editions), but [direct consumption](https://github.com/pattern-lab/patternlab-node#direct-consumption) is also encouraged.
2321

24-
## `getDefaultConfig()` ⇒ <code>object</code>
25-
26-
Returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
27-
28-
**Returns**: <code>object</code> - Returns the object representation of the `patternlab-config.json`
29-
## `version()` ⇒ <code>string</code>
30-
31-
Returns current version
32-
22+
**Kind**: global namespace
23+
**See**
24+
25+
- [patternlab.io](patternlab.io) for more documentation.
26+
- [https://github.com/pattern-lab/patternlab-node](https://github.com/pattern-lab/patternlab-node) for code, issues, and releases
27+
28+
**License**: MIT
29+
30+
* [`patternlab`](#patternlab) : <code>object</code>
31+
* _instance_
32+
* [`.version`](#patternlab+version) ⇒ <code>string</code>
33+
* [`.build`](#patternlab+build) ⇒ <code>Promise</code>
34+
* [`.getDefaultConfig`](#patternlab+getDefaultConfig) ⇒ <code>object</code>
35+
* [`.getSupportedTemplateExtensions`](#patternlab+getSupportedTemplateExtensions) ⇒ <code>Array.&lt;string&gt;</code>
36+
* [`.help`](#patternlab+help) ⇒ <code>void</code>
37+
* [`.installplugin`](#patternlab+installplugin) ⇒ <code>void</code>
38+
* [`.liststarterkits`](#patternlab+liststarterkits) ⇒ <code>Promise</code>
39+
* [`.loadstarterkit`](#patternlab+loadstarterkit) ⇒ <code>void</code>
40+
* [`.patternsonly`](#patternlab+patternsonly) ⇒ <code>Promise</code>
41+
* _static_
42+
* [`.getDefaultConfig`](#patternlab.getDefaultConfig) ⇒ <code>object</code>
43+
* [`.getVersion`](#patternlab.getVersion) ⇒ <code>string</code>
44+
* [`.server`](#patternlab.server) : <code>object</code>
45+
* [`.serve(options)`](#patternlab.server.serve) ⇒ <code>Promise</code>
46+
* [`.reload()`](#patternlab.server.reload) ⇒ <code>Promise</code>
47+
* [`.refreshCSS()`](#patternlab.server.refreshCSS) ⇒ <code>Promise</code>
48+
* [`.events`](#patternlab.events) : <code>EventEmitter</code>
49+
50+
<a name="patternlab+version"></a>
51+
52+
### `patternlab.version` ⇒ <code>string</code>
53+
Returns current version
54+
55+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
3356
**Returns**: <code>string</code> - current patternlab-node version as defined in `package.json`, as string
34-
## `build(options)` ⇒ <code>Promise</code>
57+
<a name="patternlab+build"></a>
3558

36-
Builds patterns, copies assets, and constructs user interface
59+
### `patternlab.build` ⇒ <code>Promise</code>
60+
Builds patterns, copies assets, and constructs user interface
3761

62+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
3863
**Returns**: <code>Promise</code> - a promise fulfilled when build is complete
64+
**Emits**: <code>event:PATTERNLAB_BUILD_START</code>, <code>event:PATTERNLAB_BUILD_END</code>
65+
**See**: [all events](./events.md)
3966

4067
| Param | Type | Description |
4168
| --- | --- | --- |
@@ -44,49 +71,63 @@ Many of these functions are exposed to users within [Editions](https://github.co
4471
| options.data | <code>object</code> | additional data to be merged with global data prior to build |
4572
| options.watch | <code>bool</code> | whether or not Pattern Lab should watch configured `source/` directories for changes to rebuild |
4673

47-
## `getDefaultConfig()` ⇒ <code>object</code>
74+
<a name="patternlab+getDefaultConfig"></a>
4875

49-
Returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
76+
### `patternlab.getDefaultConfig` ⇒ <code>object</code>
77+
Returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
5078

79+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
5180
**Returns**: <code>object</code> - Returns the object representation of the `patternlab-config.json`
52-
## `getSupportedTemplateExtensions()` ⇒ <code>Array.&lt;string&gt;</code>
81+
<a name="patternlab+getSupportedTemplateExtensions"></a>
5382

54-
Returns all file extensions supported by installed PatternEngines
83+
### `patternlab.getSupportedTemplateExtensions` ⇒ <code>Array.&lt;string&gt;</code>
84+
Returns all file extensions supported by installed PatternEngines
5585

86+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
5687
**Returns**: <code>Array.&lt;string&gt;</code> - all supported file extensions
57-
## `help()` ⇒ <code>void</code>
88+
<a name="patternlab+help"></a>
5889

59-
Logs usage to standard output
90+
### `patternlab.help` ⇒ <code>void</code>
91+
Logs usage to standard output
6092

93+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
6194
**Returns**: <code>void</code> - Pattern Lab API usage, as console output
62-
## `installplugin(pluginName)` ⇒ <code>void</code>
95+
<a name="patternlab+installplugin"></a>
6396

64-
Installs plugin already available via `node_modules/`
97+
### `patternlab.installplugin` ⇒ <code>void</code>
98+
Installs plugin already available via `node_modules/`
6599

100+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
66101

67102
| Param | Type | Description |
68103
| --- | --- | --- |
69104
| pluginName | <code>string</code> | name of plugin |
70105

71-
## `liststarterkits()` ⇒ <code>Promise</code>
106+
<a name="patternlab+liststarterkits"></a>
72107

73-
Fetches starterkit repositories from pattern-lab github org that contain 'starterkit' in their name
108+
### `patternlab.liststarterkits` ⇒ <code>Promise</code>
109+
Fetches starterkit repositories from pattern-lab github org that contain 'starterkit' in their name
74110

111+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
75112
**Returns**: <code>Promise</code> - Returns an Array<{name,url}> for the starterkit repos
76-
## `loadstarterkit(starterkitName, clean)` ⇒ <code>void</code>
113+
<a name="patternlab+loadstarterkit"></a>
77114

78-
Loads starterkit already available via `node_modules/`
115+
### `patternlab.loadstarterkit` ⇒ <code>void</code>
116+
Loads starterkit already available via `node_modules/`
79117

118+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
80119

81120
| Param | Type | Description |
82121
| --- | --- | --- |
83122
| starterkitName | <code>string</code> | name of starterkit |
84123
| clean | <code>boolean</code> | whether or not to delete contents of source/ before load |
85124

86-
## `patternsonly(options)` ⇒ <code>Promise</code>
125+
<a name="patternlab+patternsonly"></a>
87126

88-
Builds patterns only, leaving existing user interface files intact
127+
### `patternlab.patternsonly` ⇒ <code>Promise</code>
128+
Builds patterns only, leaving existing user interface files intact
89129

130+
**Kind**: instance property of [<code>patternlab</code>](#patternlab)
90131
**Returns**: <code>Promise</code> - a promise fulfilled when build is complete
91132

92133
| Param | Type | Description |
@@ -95,10 +136,38 @@ Many of these functions are exposed to users within [Editions](https://github.co
95136
| options.cleanPublic | <code>bool</code> | whether or not to delete the configured output location (usually `public/`) before build |
96137
| options.data | <code>object</code> | additional data to be merged with global data prior to build |
97138

98-
## `serve(options)` ⇒ <code>Promise</code>
139+
<a name="patternlab.getDefaultConfig"></a>
140+
141+
### `patternlab.getDefaultConfig` ⇒ <code>object</code>
142+
Static method that returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
143+
144+
**Kind**: static property of [<code>patternlab</code>](#patternlab)
145+
**Returns**: <code>object</code> - Returns the object representation of the `patternlab-config.json`
146+
<a name="patternlab.getVersion"></a>
147+
148+
### `patternlab.getVersion` ⇒ <code>string</code>
149+
Static method that returns current version
150+
151+
**Kind**: static property of [<code>patternlab</code>](#patternlab)
152+
**Returns**: <code>string</code> - current @pattern-lab/core version as defined in `package.json`
153+
<a name="patternlab.server"></a>
99154

100-
Build patterns, copies assets, and constructs user interface. Watches configured `source/` directories, and serves all output locally
155+
### `patternlab.server` : <code>object</code>
156+
Server module
101157

158+
**Kind**: static property of [<code>patternlab</code>](#patternlab)
159+
160+
* [`.server`](#patternlab.server) : <code>object</code>
161+
* [`.serve(options)`](#patternlab.server.serve) ⇒ <code>Promise</code>
162+
* [`.reload()`](#patternlab.server.reload) ⇒ <code>Promise</code>
163+
* [`.refreshCSS()`](#patternlab.server.refreshCSS) ⇒ <code>Promise</code>
164+
165+
<a name="patternlab.server.serve"></a>
166+
167+
#### `server.serve(options)` ⇒ <code>Promise</code>
168+
Build patterns, copies assets, and constructs user interface. Watches configured `source/` directories, and serves all output locally
169+
170+
**Kind**: static method of [<code>server</code>](#patternlab.server)
102171
**Returns**: <code>Promise</code> - a promise fulfilled when build is complete
103172

104173
| Param | Type | Description |
@@ -108,6 +177,30 @@ Many of these functions are exposed to users within [Editions](https://github.co
108177
| options.data | <code>object</code> | additional data to be merged with global data prior to build |
109178
| options.watch | <code>bool</code> | **ALWAYS OVERRIDDEN to `true`** whether or not Pattern Lab should watch configured `source/` directories for changes to rebuild |
110179

180+
<a name="patternlab.server.reload"></a>
181+
182+
#### `server.reload()` ⇒ <code>Promise</code>
183+
Reloads any active live-server instances
184+
185+
**Kind**: static method of [<code>server</code>](#patternlab.server)
186+
**Returns**: <code>Promise</code> - a promise fulfilled when operation is complete
187+
<a name="patternlab.server.refreshCSS"></a>
188+
189+
#### `server.refreshCSS()` ⇒ <code>Promise</code>
190+
Reloads CSS on any active live-server instances
191+
192+
**Kind**: static method of [<code>server</code>](#patternlab.server)
193+
**Returns**: <code>Promise</code> - a promise fulfilled when operation is complete
194+
<a name="patternlab.events"></a>
195+
196+
### `patternlab.events` : <code>EventEmitter</code>
197+
**Kind**: static property of [<code>patternlab</code>](#patternlab)
198+
**See**
199+
200+
- [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
201+
- [All Pattern Lab events](./events.md)
202+
203+
111204
* * *
112205

113206
[Pattern Lab](http://patternlab.io) Node is [MIT Licensed](https://github.com/pattern-lab/patternlab-node/blob/master/LICENSE)

‎packages/core/docs/events.md

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ Learn more about [Creating Plugins](https://github.com/pattern-lab/patternlab-no
1818
### `EVENTS` ⏏
1919

2020
**Kind**: Exported constant
21-
<a name="module_Events--EVENTS..PATTERNLAB_BUILD_PATTERN_START"></a>
21+
<a name="module_Events--EVENTS..PATTERNLAB_BUILD_START"></a>
2222

23-
#### `EVENTS~PATTERNLAB_BUILD_PATTERN_START`
23+
#### `EVENTS~PATTERNLAB_BUILD_START`
2424

2525
Emitted before any logic run inside `build()`, which is the entry point for single builds, pattern-only builds, run singly or when watched.
2626

@@ -31,6 +31,19 @@ Emitted before any logic run inside `build()`, which is the entry point for sing
3131
| ---------- | ------------------- | ----------------- |
3232
| patternlab | <code>object</code> | global data store |
3333

34+
<a name="module_Events--EVENTS..PATTERNLAB_BUILD_END"></a>
35+
36+
#### `EVENTS~PATTERNLAB_BUILD_END`
37+
38+
Emitted after all logic run inside `build()`, which is the entry point for single builds, pattern-only builds, run singly or when watched.
39+
40+
**Kind**: inner property of [<code>EVENTS</code>](#exp_module_Events--EVENTS)
41+
**Properties**
42+
43+
| Name | Type | Description |
44+
| ---------- | ------------------- | ----------------- |
45+
| patternlab | <code>object</code> | global data store |
46+
3447
<a name="module_Events--EVENTS..PATTERNLAB_PATTERN_ITERATION_END"></a>
3548

3649
#### `EVENTS~PATTERNLAB_PATTERN_ITERATION_END`

‎packages/core/scripts/api.handlebars

Lines changed: 2 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -10,50 +10,10 @@
1010

1111
``` javascript
1212
const config = require('./patternlab-config.json');
13-
const patternlab = require('patternlab-node')(config);
13+
const patternlab = require('@pattern-lab/core')(config);
1414
```
1515

16-
## Events
17-
18-
Pattern Lab emits numerous [events](./events.md).
19-
20-
## Functions
21-
22-
Many of these functions are exposed to users within [Editions](https://github.com/pattern-lab/patternlab-node#editions), but [direct consumption](https://github.com/pattern-lab/patternlab-node#direct-consumption) is also encouraged.
23-
24-
{{#orphans ~}}
25-
{{>heading-indent}}{{>sig-name}}
26-
27-
{{>deprecated~}}
28-
{{>description~}}
29-
{{>summary~}}
30-
{{>augments~}}
31-
{{>implements~}}
32-
{{>mixes~}}
33-
{{>default~}}
34-
{{>chainable~}}
35-
{{>overrides~}}
36-
{{>returns~}}
37-
{{>category~}}
38-
{{>throws~}}
39-
{{>fires~}}
40-
{{>this~}}
41-
{{>access~}}
42-
{{>readOnly~}}
43-
{{>requires~}}
44-
{{>customTags~}}
45-
{{>see~}}
46-
{{>since~}}
47-
{{>version~}}
48-
{{>authors~}}
49-
{{>license~}}
50-
{{>copyright~}}
51-
{{>todo~}}
52-
{{>params~}}
53-
{{>properties~}}
54-
{{>examples~}}
55-
56-
{{/orphans~}}
16+
{{>main}}
5717

5818
* * *
5919

0 commit comments

Comments
 (0)