doxie --inject

A plugin for doxie.
Join rendered docs and inject them into your readme.

Installation

doxie --inject is a plugin for the command-line tool doxie. dox produces compatible data from jsDoc comments. Install all three if you haven’t already:

$ npm install --global dox doxie doxie.inject

Usage

1. Write a readme

…or some other document in Markdown or HTML. Put the markers <!-- @doxie.inject start --> and <!-- @doxie.inject end --> somewhere in it.

1. Profit!

Render your docs with doxie – here we use doxie --render for that. Then --inject them into your readme.

$ dox | doxie --render --inject

We’ll join your docs into one string and replace all content between the markers with that string.

1. Options!

You can set things up with options:

--inject( <option> <argument>)*

For example:

$ doxie --render \
$   --inject into 'My docs.md' as public

Read on!

Options

--inject as <marker name>

Apart from the default markers you can have named markers. This way you can inject different docs at different places.

Put them in your readme: <!-- @doxie.inject start my-marker --> and <!-- @doxie.inject end my-marker -->.

Then inject your docs:

$ doxie --inject as my-marker

--inject into <target document>

By default we’ll inject your docs into README.md, Readme.md, or readme.md in the current working directory. But if you want another target, no problem:

$ doxie --inject into ./documentation/my-docs.html

Programmatic usage

You can use doxie.inject directly with doxie-core. Install both if you haven’t already:

$ npm install doxie-core doxie.inject

Use it like this:

inject({input, [as]})
  → plugin

Parameters (properties of an object):

• input
  ^{type: String (or cast to String) | required}
  The content of a readme – or another Markdown / HTML document.

• as
  ^{type: String or null (or cast to String) | optional | default: null}
  Same as --inject as <marker name>.

Returned value:

• plugin
  ^{type: Function}
  Pass this to doxie-core.

plugin(…)
  → {['doxie.inject']: {output}, …}

Returned properties:

• ['doxie.inject'].output
  ^{type: String}
  The resulting content of the readme – with your docs injected.

• …
  Other properties required by doxie-core.

Example:

const doxie = require('doxie-core');
const render = require('doxie.render');
const inject = require('doxie.inject');
 
doxie([
  render(require('./.doxie.render.js')),
  inject({
    input:
`#  My readme  #
 
##  Usage  ##
<!-- @doxie.input start usage -->
(this will be replaced)
<!-- @doxie.input end usage -->
 
##  License: MIT  ##
`,
    as: 'usage',
  }),
])([/* my docs’ data */]);
//» {
//    'doxie.inject': {output: "
//      #  My readme  #
//      
//      ##  Usage  ##
//      <!-- @doxie.input start usage -->
//      
//      ###  myFancyFunction(a, b, c)  ###
//      
//      Parameters:
//      
//      * a
//      * b
//      * c
//      
//      Return value:
//      
//      * d
//      <!-- @doxie.input end usage -->
//      
//      ##  License: MIT  ##
//    "},
//    …
//  }
 

License

MIT © Studio B12 GmbH