Skip to content

Latest commit

 

History

History
353 lines (255 loc) · 8.71 KB

api.md

File metadata and controls

353 lines (255 loc) · 8.71 KB
Raw

back to README.md

Configuration

This plugin applies the following configuration

Templates

docs/api.md.hbs

{{#moduleConfig}}

# API-Documentation

This page describes the API of this Bootprint-module

* [Templates](#templates)
  * [Partials](#partials)
* [Handlebars Helpers](#helpers)
{{#each handlebars.helpers}}
{{#if .}} 
{{#withPackageOf .}}
  * from [{{@package.name}}@{{@package.version}}](#helpers-{{htmlId @package.name}})
{{/withPackageOf}}
{{/if}}
{{/each}}
* [LessCSS](#lesscss)
    
# Templates

{{#each handlebars.callHierarchy.children}}
    
{{>bootprint/hbs-file.md .}}
    
{{/each}}

## Partials

{{#each handlebars.partials}}
{{>bootprint/hbs-file.md name=@key type='partial'}}    
{{/each}}
     
{{!-- ##### Handlebars Helpers ##### --}}
{{#each handlebars.helpers}}

{{#if .}}

{{#withPackageOf .}}
<a name="helpers-{{htmlId @package.name}}"></a>
# Helpers ({{@package.name}})

(from [{{@package.name}}@{{@package.version}}/{{@relativePath}}]({{@url}})
{{/withPackageOf}})

{{jsdoc .}}
{{else}}
## Inlined helpers 
    
*Some helpers are defined directly in the configuration and not via path-reference to a module.
The docs for these helpers cannot be generated and are missing on this page.
If you are the author of this package, please consider putting the helpers into a distinct file
and adding only the path to the configuration.*
    
{{/if}}

{{/each}}

# LessCSS 

## Main LessCSS-files

{{#each less.main}}
* {{#withPackageOf .}}[{{@package.name}}@{{@package.version}}/{{@relativePath}}]({{@url}}){{/withPackageOf}}  
{{/each}}
    
## LessCSS include paths

{{#each less.paths}}
* {{#withPackageOf .}}[{{@package.name}}@{{@package.version}}/{{@relativePath}}]({{@url}}){{/withPackageOf}}
{{/each}}


{{/moduleConfig}}

Partials

api.md.hbs

# API

see [docs/api.md](docs/api.md)

bootprint/call-hierarchy.md.hbs

{{!--
This partial renders a call hierarchy of templates and partials as tree. The input
is a JSON object containing nested tree-nodes in a `children`-property.
The `renderTree`-helper is used to render the tree (so the input must be compatible
to this helper. The `callHierarchy` generated by the docEngine of `customize-engine-handlebars`
is supposed to be passed in here.

@param {object} tree an object of the same structure as the 'callHierarchy' property 
generated by the docEngine of `customize-engine-handlebars`
--}}

{{#renderTree .}}
{{#if name~}}
<a href="#{{type}}-{{htmlId name}}">{{name}}</a>
{{/if}}
{{~#if cycleFound}}
<span title="cycle detected"><i>(&#x1F501; cycle detected)</i> </span>
{{else}}
{{!-- Comment is omitted if this is a cycle --}}
{{~#if comments.[0]}}
<i>{{abbrev comments.[0] 50}}</i>
{{~/if}}
{{/if}}
{{/renderTree}}

bootprint/example-description.md.hbs

{{!-- 
  This partial is included just below the ussage example.
  You can override this partial in order to add a more detailed explaination
  about what your specific example.json is an where it comes from.
 
  You should at least cite your source if you have taken the example from
  somewhere else.
 
  @api public
--}}
`example.json` can be found in [examples/example.json](examples/example.json) in this project.

bootprint/hbs-file.md.hbs

{{!-- 
   Partial for including bootprint Handlebars-files into the documentation
   @param {string} name the filename
   @param {string} path the full path to the file
   @param {string} contents the file's contents
   @param {string[]} comments an array of extracted comments
   @param {string} type 'partial' or 'template'
--}}
<a name="{{type}}-{{htmlId name}}"></a>
### {{name}}

<table>
    <tr>
        <th>Source file</th>
        <td>
            {{#withPackageOf path~}}
                <a href="{{@url}}">{{@package.name}} @ {{@package.version}} / {{@relativePath}}</a>
            {{~/withPackageOf}}
        </td>
    </tr>
    {{#if callsPartial.length}}
        <tr>
            <th>Uses partials</th>
            <td>
                {{#each callsPartial}}
                    <a href="#partial-{{htmlId name}}">{{name}}</a>
                    {{~#unless @last}}, {{/unless}}
                {{/each}}
            </td>
        </tr>
    {{/if}}
    {{#if calledBy.length}}
        <tr>
            <th>Used by</th>
            <td>
                {{#each calledBy}}
                    <a href="#{{type}}-{{htmlId name}}">{{name}}</a>
                    {{~#unless @last}}, {{/unless}}
                {{/each}}
            </td>
        </tr>
    {{/if}}
    {{#if children}}
        <tr>
            <th>Structure</th>
            <td>{{>bootprint/call-hierarchy.md tree=.}}</td>
        </tr>
    {{/if}}
</table>

{{#if comments.[0]}}
{{#codeBlock}}
{{comments.[0]}}
{{/codeBlock}}
{{/if}}

installation.md.hbs

{{#unless package.private}}
# Installation

```
npm -g install bootprint
npm -g install {{package.name}}
```
{{/unless}}

usage.md.hbs

## Usage

{{#if (exists 'examples')}}

After installing the package globally, you can run bootprint with the command

```bash
bootprint {{shortModuleName package.name}} {{#withPackageOf 'examples/example.json'}}{{@rawUrl}}{{/withPackageOf}} target
```

{{>bootprint/example-description.md}}

Bootprint will then generate the following files:

{{runBootprint '.' './examples/example.json' 'examples/target'}} 

{{/if}}

## Customizing

You can write your own module that customizes the partials and helpers in this module
(see [the bootprint documentation](https://github.com/bootprint/bootprint/blob/master/doc/modules.md)) for details.

The entrypoint JavaScript-file of such a module would look like.

```js
module.exports = function (customize) {
  return customize
    .load(require('{{package.name}}'))
    .merge({
      // You customizations here
    })

// Add "package" metadata. This can be evaluated by documentation generators
module.exports.package = require('./package')
```

Helpers

helpers

Default Handlebars-helpers for Thought

Kind: global variable

helpers.codeBlock() ⇒ Promise.<string>

Create a markdown code-block with enough backticks

The surrounding fences of a code-block must have more backticks than the maximum number of consecutive backticks in the contents (escaping backticks github/markup#363). This block-helper creates enough and at least three.

Kind: static method of helpers
Returns: Promise.<string> - the string containing the
Access: public
Example

{{#codeBlock lang='hbs'}}
Some markdown hbs template
{{/codeBlock}}

helpers.moduleConfig(options) ⇒ Promise

Continue with the thought-configuration of the current plugin

The helper loads the thought-configuration from the plugin in the current working directory and passed the resulting JSON as context to the content-block.

Kind: static method of helpers
Access: public

Param
options

helpers.abbrev(text, limit)

Abbreviate a text to be no longer than a given limit.

Kind: static method of helpers
Access: public

Param Type Description
text string the text
limit number the maximum length (excluding the '...' that is added if the text was limited)

helpers.runBootprint(module, input, target) ⇒ *

Kind: static method of helpers
Access: public

Param
module
input
target

helpers.shortModuleName(name)

Returns the stripped module name (remove the "bootprint-"-prefix if applicable

Kind: static method of helpers
Access: public

Param Type Description
name string the module name