File Tree

Create an HTML rendered package README file tree.

Usage

var build = require( '@stdlib/_tools/docs/www/readme-fragment-file-tree' );

build( dest, [options,] clbk )

Asynchronously creates an HTML rendered package README file tree.

build( './build', done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished' );
}

The function accepts the following options:

• dir: root directory from which to search for package READMEs. May be either an absolute path or a path relative to the current working directory. Default: current working directory.
• pattern: glob pattern used to find packages. Default: '**/package.json' (note: pattern must end with package.json).
• ignore: list of glob patterns used to exclude matches.
• base: internal URL base path.

To search from an alternative directory, set the dir option.

var opts = {
    'dir': '/foo/bar/baz'
};

build( './build', opts, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished' );
}

To provide an alternative include filter, set the pattern option.

var opts = {
    'pattern': '**/foo/**/package.json'
};

build( './build', opts, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished' );
}

To exclude matches, set the ignore option.

var opts = {
    'ignore': [
        'node_modules/**',
        'build/**',
        'reports/**'
    ]
};

build( './build', opts, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished' );
}

To have internal URLs of the READMEs link to relative (or absolute) documentation pages with a specified base path, set the base option.

var opts = {
    'base': '/docs/api/v0.0.90/'
};

build( './build', opts, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished' );
}

Notes

• The output directory may be either a relative or absolute path. If provided a relative path, the implementation resolves the output directory relative to the current working directory.
• The implementation resolves package READMEs by checking for a README.md file in the directory containing a package's package.json file.

Examples

var mkdir = require( 'fs' ).mkdirSync;
var resolve = require( 'path' ).resolve;
var exists = require( '@stdlib/fs/exists' ).sync;
var build = require( '@stdlib/_tools/docs/www/readme-fragment-file-tree' );

var dpath = resolve( __dirname, 'build' );

var opts = {
    'dir': './lib/node_modules',
    'ignore': [
        'benchmark/**',
        'bin/**',
        'build/**',
        'docs/**',
        'etc/**',
        'examples/**',
        'reports/**',
        'scripts/**',
        'test/**'
    ]
};

if ( !exists( dpath ) ) {
    mkdir( dpath );
}
build( dpath, opts, done );

function done( error ) {
    if ( error ) {
        throw error;
    }
    console.log( 'Finished!' );
}

---

CLI

Usage

Usage: readme-fragment-file-tree [options] [<dir>] --out <dir>

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --pattern pattern     Inclusion glob pattern.
         --ignore pattern      Exclusion glob pattern.
         --base path           Internal URL base path.
  -o,    --out directory       Output directory.

Notes

• If not provided a dir argument, the current working directory is the search directory.

• To provide multiple exclusion glob patterns, set multiple --ignore option arguments.

  $ readme-fragment-file-tree --ignore=node_modules/** --ignore=build/** --ignore=reports/** --out=./build

Examples

$ readme-fragment-file-tree -o ./build