Extensible system for parsing and generating documentation. It just freaking works!
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.
Project is semantically & automatically released on CircleCI with new-release and its New Release GitHub App.
(TOC generated by verb using markdown-toc)
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
Generated using docks.
Constructor that gives you methods.
Returns
Object
instance ofDocks
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 ofDocks
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 withComment
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);
});
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
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.
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 💻 📖 💬 👀 🔍 |
---|
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.