docks

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.

Table of Contents

• Install
• CLI
• API
  • src/index.js
    • docks
    • .use
    • .parse
  • src/plugins/render.js
    • .renderFileSync
    • .renderFile
    • .renderTextSync
    • .renderText
    • .renderSync
    • .render
• See Also
• Contributing
  • Follow the Guidelines
  • Support the project
  • OPEN Open Source
  • Wonderful Contributors
• License

(TOC generated by verb using markdown-toc)

Install

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

$ yarn add docks

CLI

For CLI usage install it globally or as devDependency.
To make it work, you should add <!-- docks-start --> and <!-- docks-end --> placeholders in your existing file or provide non existing file to --outfile flag. If no --outfile flag is given, then it will try to search those HTML comments on README.md and add the API documentation there.

docks # or docks --outfile docs/API.md 

Also, by default it collects documentation from all src/**/*.{js,jsx,ts,tsx} files, but you can give another glob pattern. For example run docks bar/*.js. Only block comments with a @public tag are collected and used to render the docs.

API

Generated using docks.

src/index.js

docks

Constructor that gives you methods.

Returns

• Object instance of Docks

.use

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';
});

.parse

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);

src/plugins/render.js

.renderFileSync

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);

.renderFile

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);
});

.renderTextSync

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);

.renderText

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);
});

.renderSync

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

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… more | homepage
• charlike: Small, fast and streaming project scaffolder with support for hundreds… more | homepage
• gitcommit: Lightweight and joyful git commit replacement. Conventional Commits compliant. | homepage
• new-release: MIRROR] Publish project to NPM following Conventional Commits specification and… more | homepage
• xaxa: Zero-config linting, powered by few amazing unicorns, AirBnB & Prettier. | homepage

back to top

Contributing

Follow the Guidelines

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.

Support the project

Become a Partner or Sponsor? 💵 Check the Partner, Sponsor or Omega-level tiers! 🎉 You can get your company logo, link & name on this file. It's also rendered on package page in npmjs.com and yarnpkg.com sites too! 🚀

Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. ✨

OPEN Open Source

This project is following OPEN Open Source model

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is built on collective efforts and it's not strongly guarded by its founders.

There are a few basic ground-rules for its contributors

1. Any significant modifications must be subject to a pull request to get feedback from other contributors.
2. Pull requests to get feedback are encouraged for any other trivial contributions, but are not required.
3. Contributors should attempt to adhere to the prevailing code-style and development workflow.

Wonderful Contributors

Thanks to the hard work of these wonderful people this project is alive! It follows the all-contributors specification.
Don't hesitate to add yourself to that list if you have made any contribution! ;) See how, here.

Charlike Mike Reagent 💻 📖 💬 👀 🔍

Consider showing your support to them. 💖

License

Copyright (c) 2018-present, Charlike Mike Reagent <[e-mail]> & contributors.
Released under the Apache-2.0 License.

---

This file was generated by verb-generate-readme, v0.8.0, on January 31, 2019.