Skip to content

tunnckoCore/docks

Folders and files

NameName
Last commit message
Last commit date

Latest commit

author
Charlike Mike Reagent
Nov 1, 2018
5c9b2b7 · Nov 1, 2018

History

19 Commits
Jul 29, 2018
Nov 1, 2018
Jul 29, 2018
Jul 29, 2018
Jul 29, 2018
Jul 29, 2018
Nov 1, 2018
Jul 29, 2018
Jul 29, 2018
Jul 29, 2018
Nov 1, 2018
Nov 1, 2018
Jul 30, 2018

Repository files navigation

docks npm version github release License

Extensible system for parsing and generating documentation. It just freaking works!

Code style CircleCI linux build CodeCov coverage status DavidDM dependency status Renovate App Status Make A Pull Request Semantically Released

If you have any how-to kind of questions, please read the Contributing Guide and Code of Conduct documents.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Conventional Commits Become a Patron Share Love Tweet NPM Downloads Weekly NPM Downloads Monthly NPM Downloads Total

Project is semantically & automatically released on CircleCI with new-release and its New Release GitHub App.

Table of Contents

(TOC generated by verb using markdown-toc)

Install

This project requires Node.js ^8.9.0 || ^10.6.0. Install it using yarn or npm.
We highly recommend to use Yarn when you think to contribute to this project.

$ yarn add docks

API

Generated using docks.

Constructor that gives you methods.

Returns

  • Object instance of Docks

A plugin is a function that may extend the core functionality, or if it returns another function it is called for each block comment.

Look at src/plugins/ folder to see the built-in ones.

Params

  • plugin {Function} with signature like (docks) => (comment) => {}

Returns

  • Object instance of Docks

Examples

import docks from 'docks';

const app = docks();

// extending the core
app.use((self) => {
  self.foobar = 123
});

console.log(app.foobar); // => 123

// Or plugin that will be called on each block comment
app.use(() => (comment) => {
  comment.hoho = 'okey'
});

Parses given input using @babel/parser and passes all block comments to doctrine which is JSDoc parser. It also applies all the "Smart Plugins". Smart plugin is the function that is returned from each function passed to the app.use method.

Params

  • input {string} file content which contains document block comments

Returns

  • Array<Comment> an array with Comment objects.

Examples

const app = docks();

const smartPlugin = (comment) => {
  // do some stuff witht he Comment object.
};

app.use((self) => smartPlugin);

const cmts = app.parse('some cool stuff with block comments');
console.log(cmts);

Render single fp file to a documentation string.

Params

  • fp {string} absolute filepath to file to look for doc comments.

Returns

  • string

Examples

const app = docks();
const output = app.renderFileSync('path/to/source/file/with/comments');
console.log(output);

Render single fp file to a documentation string, asynchronously.

Params

  • fp {string} absolute file path to look for doc comments.

Returns

  • Promise<string>

Examples

const app = docks();
app.renderFile('path/to/source/file/with/comments').then((output) => {
  console.log(output);
});

Create a documentation output string from given comments. Use app.parse method to generate such list of Comment objects.

Params

  • comments {Array<Comment>}

Returns

  • string

Examples

const app = docks();

const comments = app.parse('some string with block comments');
const output = app.renderTextSync(comments);
console.log(output);

Create a documentation output string from given comments, asynchronously. Use app.parse method to generate such list of Comment objects.

Params

  • comments {Array<Comment>}

Returns

  • Promise<string>

Examples

const app = docks();

const comments = app.parse('some string with block comments');
app.renderText(comments).then((output) => {
  console.log(output);
});

Render a list of filepaths to a documentation string.

Params

  • files {Array<string>} list of absolute file paths to look for doc comments.

Returns

  • string

Examples

const proc = require('process');
const path = require('path');
const app = docks();

const files = ['src/index.js', 'src/bar.js'].map((fp) => {
  return path.join(proc.cwd(), fp);
})

const output = app.renderSync(files);
console.log(output);

Render a list of filepaths to a documentation, asynchronously.

Params

  • files {Array<string>} list of absolute file paths to look for doc comments.

Returns

  • Promise<string>

Examples

const proc = require('process');
const path = require('path');
const app = docks();

const files = ['src/index.js', 'src/bar.js'].map((fp) => {
  return path.join(proc.cwd(), fp);
})

app.render(files).then((output) => {
  console.log(output);
});

back to top

See Also

Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!

  • asia: Blazingly fast, magical and minimalist testing framework, for Today and Tomorrow | homepage
  • charlike: Small, fast, simple and streaming project scaffolder for myself, but not… more | homepage
  • gitcommit: Lightweight and joyful git commit replacement. Conventional Commits compliant. | homepage
  • new-release: A stable alternative to semantic-release. Only handles NPM publishing and nothing… more | homepage
  • xaxa: Zero-config linting, powered by few amazing unicorns, AirBnB & Prettier. | homepage

back to top

Contributing

Please read the Contributing Guide and Code of Conduct documents for advices.
For bugs reports and feature requests, please create an issue or ping @tunnckoCore at Twitter.

Contributors

Thanks to the hard work of these wonderful people this project is alive and it also follows the all-contributors specification.
Pull requests, stars and all kind of contributions are always welcome. ✨


Charlike Mike Reagent

💻 📖 💬 👀 🔍

License

Copyright (c) 2018-present, Charlike Mike Reagent <olsten.larck@gmail.com>.
Released under the Apache-2.0 License.


This file was generated by verb-generate-readme, v0.8.0, on November 01, 2018.