npm package: @kingjs/tools.expand-readme-template
Description: Generates `README.md` from a `README.t.md` given `package.json`.
Latest version: 1.0.7
Deprecated: @see @kingjs/expand-readme

# @[kingjs][@kingjs]/[tools][ns0].[expand-readme-template][ns1]
Generates `README.md` from a `README.t.md` given `package.json`.
## Usage
Give a `package.json` like this:
```js
{
  "name": "@kingjs/ns0.ns1.example",
  "version": "1.0.0",
  "description": "Example description.",
  "main": "index.js",
  "repository": {
    "url": "https://repository.kingjs.net/ns0.ns1.example"
  },
  "license": "MIT",
  "dependencies": {},
  "readmeTemplate": "./md/README.t.md",
  "devDependencies": {
    "@kingjs/tools.expand-readme-template": "^1.0.5"
  }
}

```
And a `index.js` like this:
```js
/**
 * @this any This comment
 * @param foo Foo comment
 * @param [bar] Bar comment
 * @param [baz] Baz comment
 * @returns The return comment.
 */
function example(foo, bar, baz) { }

```
And a `md/README.t.md` like this:
````
# @[kingjs][@kingjs]/${join('[${value}][ns${i}]', segments, '.')}
${description}
${canInclude('./test/readme.js') ? expand('./USAGE.t.md') : ''}
${api ? expand('./API.t.md') : ''}
## Remarks
Run in directory containing `package.json`.
${expand('./FOOTER.t.md')}

[@kingjs]: ${npmjs}kingjs
${join('[ns${i}]: ${npmjs}@kingjs/${value}', namespaces, '\n')}

````
And a `md/USAGE.t.md` like this:
````
## Usage
```js
${include('./test/readme.js').replace('..', name)}
```

````
And a `test/readme.js` like this:
```js
var assert = require('assert')

var test = require('..');

function readMe() {
  // example code here
}
readMe();
```
And a `md/API.t.md` like this:
````
## API
```ts
${api}
```
### Parameters
${join('- `${key}`: ${value}', parameters, '\n', signature)}
${returns ? expand('./RETURNS.t.md') : ''}
````
And a `md/RETURNS.t.md` like this:
````
### Returns
${returns}
````
And a `md/FOOTER.t.md` like this:
````
## Install
With [npm](https://npmjs.org/) installed, run
```
$ npm install ${name}
```
## Source
${repository}
## License
${license}

![Analytics](https://analytics.kingjs.net/${join('${value}', segments, '/')})
````
Running `$npx ert` will produce a `README.md` like this:
````

# @[kingjs][@kingjs]/[ns0][ns0].[ns1][ns1].[example][ns2]
Example description.
## Usage
```js
var assert = require('assert')

var test = require('@kingjs/ns0.ns1.example');

function readMe() {
  // example code here
}
readMe();
```

## API
```ts
example(this, foo[, bar[, baz]])
```
### Parameters
- `this`: This comment
- `foo`: Foo comment
- `bar`: Bar comment
- `baz`: Baz comment
### Returns
The return comment.
## Remarks
Run in directory containing `package.json`.
## Install
With [npm](https://npmjs.org/) installed, run
```
$ npm install @kingjs/ns0.ns1.example
```
## Source
https://repository.kingjs.net/ns0.ns1.example
## License
MIT

![Analytics](https://analytics.kingjs.net/ns0/ns1/example)

[@kingjs]: https://www.npmjs.com/package/kingjs
[ns0]: https://www.npmjs.com/package/@kingjs/ns0
[ns1]: https://www.npmjs.com/package/@kingjs/ns0.ns1
[ns2]: https://www.npmjs.com/package/@kingjs/ns0.ns1.example

````
## Remarks
The tool takes no command line arguments. Instead:
* The tool expects to find a `project.json` in the directory from which it's launched. 
* It then looks for a `readmeTemplate` element in the `package.json` and tries to load that value as a relative path or as a package for use as the readme template. 
  * If a package, it expects that package's `main` to be a `t.md` template file. 
* If no `readmeTemplate` is found then it searches the current directory for `README.t.md`. 
* Once the template is found, it's expanded into a `README.md` file in the current directory. 

Expansion is preformed by treating the `README.t.md` files a js template literal that has the following variables in scope:
## Variables
The following variables are in scope as the template expands:

* `npmjs` -- `https://www.npmjs.com/package/`

From `package.json`:
* `name`
* `version`
* `description`
* `license`
* `repository`

From the package name:
* `namespaces`: Array of namespaces. 
  * E.g. `@kingjs/foo-bar.baz.moo` -> [`foo-bar`, `foo-bar.baz`];
* `segments`: Array of the segments comprising the namespace.
  * E.g. `@kingjs/foo-bar.baz.moo` -> [`foo-bar`, `baz`];

From the first `JSDoc` comment found in the file pointed at by the `main` element of the `package.json` (typically `index.js`):
* `parameters[name]` -- `@param` comment for `name`
* `parameters.this` -- `@this` comment
* `returns` -- `@returns` comment
* `summary` -- `@summary` comment
* `api` -- Mozilla signature 
  * E.g. `foo(bar[, [baz[, moo]]])`. 
  * Optional parameters names are enclosed in square brackets. 
    * E.g. `/** @params [baz] My baz comment. */`

Functions:
* `include(relPath)` -- Include the content of the file at `relPath` using the directory of `project.json` as the base path. 
* `canInclude(relPath)` -- Test if `include(relPath)` will find a file.
* `expand(relPath)` -- Includes and expands the content of the file at the `relPath` using the directory of the readme template as the base path.
* `canExpand(relPath)` -- Test if `expand(relPath)` will find a file.
* `join(template, source,[ separator[, keys]])` -- Joins the expansions of `template` for each `key`/`value` pair of `source` with `separator` ordered by `keys` while also introducing loop iteration variable `i`.

## Install
With [npm](https://npmjs.org/) installed, run
```
$ npm install -g @kingjs/tools.expand-readme-template
$ npx ert
```
## License
MIT

![Analytics](https://analytics.kingjs.net/tools/expand-readme-template)

[@kingjs]: https://www.npmjs.com/package/kingjs
[ns0]: https://www.npmjs.com/package/@kingjs/tools
[ns1]: https://www.npmjs.com/package/@kingjs/tools.expand-readme-template