Extensible system for parsing and generating documentation. It just freaking works!
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.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
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.
Generated using docks.
Constructor that gives you methods.
Returns
Object instance of DocksA 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 DocksExamples
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 commentsReturns
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
stringExamples
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
stringExamples
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
stringExamples
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!
git commit replacement. Conventional Commits compliant. | homepagePlease 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.
Become a Partner or Sponsor? :dollar: Check the Partner, Sponsor or Omega-level tiers! :tada: 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! :rocket:
Not financial support? Okey! Pull requests, stars and all kind of contributions are always welcome. :sparkles:
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
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. :sparkling_heart:
Copyright (c) 2018-present, Charlike Mike Reagent <mameto2011@gmail.com> & contributors.
Released under the Apache-2.0 License.
This file was generated by verb-generate-readme, v0.8.0, on January 31, 2019.
FAQs
Extensible system for parsing and generating documentation. It just freaking works!
The npm package docks receives a total of 16 weekly downloads. As such, docks popularity was classified as not popular.
We found that docks demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."