From 271fdc1cacdc32a6cdbda601f49c92126d2c64ba Mon Sep 17 00:00:00 2001 From: Charlike Mike Reagent Date: Thu, 1 Nov 2018 04:43:03 +0200 Subject: [PATCH] feat(cli): better defaults and --outfile resolves #3 Signed-off-by: Charlike Mike Reagent --- .verb.md | 4 +- README.md | 201 +-------------------------------------------------- docs/API.md | 201 --------------------------------------------------- package.json | 6 +- src/cli.js | 37 ++++++++-- 5 files changed, 39 insertions(+), 410 deletions(-) delete mode 100644 docs/API.md diff --git a/.verb.md b/.verb.md index 26720d6..ca0d7f0 100644 --- a/.verb.md +++ b/.verb.md @@ -36,7 +36,9 @@ $ yarn add {%= name %} ``` ## API -{%= ifExists('./docs/API.md', include('./docs/API.md')) %} + + + **[back to top](#thetop)** diff --git a/README.md b/README.md index 9b97016..3238284 100644 --- a/README.md +++ b/README.md @@ -27,17 +27,6 @@ Project is [semantically](https://semver.org) & automatically released on [Circl ## Table of Contents - [Install](#install) - [API](#api) - * [src/index.js](#srcindexjs) - + [docks](#docks) - + [.use](#use) - + [.parse](#parse) - * [src/plugins/render.js](#srcpluginsrenderjs) - + [.renderFileSync](#renderfilesync) - + [.renderFile](#renderfile) - + [.renderTextSync](#rendertextsync) - + [.renderText](#rendertext) - + [.renderSync](#rendersync) - + [.render](#render) - [See Also](#see-also) - [Contributing](#contributing) - [Contributors](#contributors) @@ -54,193 +43,9 @@ $ yarn add docks ``` ## API -_Generated using [docks](http://npm.im/docks)._ -### [src/index.js](/src/index.js) - -#### [docks](/src/index.js#L47) -Constructor that gives you methods. - -**Returns** -- `Object` instance of `Docks` - -#### [.use](/src/index.js#L79) -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/](/src/plugins) folder to see the built-in ones. - -**Params** -- `plugin` **{Function}** with signature like `(docks) => (comment) => {}` - -**Returns** -- `Object` instance of `Docks` - -**Examples** -```javascript -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](/src/index.js#L112) -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` an array with `Comment` objects. - -**Examples** -```javascript -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](/src/plugins/render.js) - -#### [.renderFileSync](/src/plugins/render.js#L50) -Render single `fp` file to a documentation string. - -**Params** -- `fp` **{string}** absolute filepath to file to look for doc comments. - -**Returns** -- `string` - -**Examples** -```javascript -const app = docks(); -const output = app.renderFileSync('path/to/source/file/with/comments'); -console.log(output); -``` - -#### [.renderFile](/src/plugins/render.js#L70) -Render single `fp` file to a documentation string, asynchronously. - -**Params** -- `fp` **{string}** absolute file path to look for doc comments. - -**Returns** -- `Promise` - -**Examples** -```javascript -const app = docks(); -app.renderFile('path/to/source/file/with/comments').then((output) => { - console.log(output); -}); -``` - -#### [.renderTextSync](/src/plugins/render.js#L95) -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** -```javascript -const app = docks(); - -const comments = app.parse('some string with block comments'); -const output = app.renderTextSync(comments); -console.log(output); -``` - -#### [.renderText](/src/plugins/render.js#L116) -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` - -**Examples** -```javascript -const app = docks(); - -const comments = app.parse('some string with block comments'); -app.renderText(comments).then((output) => { - console.log(output); -}); -``` - -#### [.renderSync](/src/plugins/render.js#L140) -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** -```javascript -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](/src/plugins/render.js#L170) -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` - -**Examples** -```javascript -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](#thetop)** @@ -273,7 +78,7 @@ Released under the [Apache-2.0 License][license-url]. --- -_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on August 11, 2018._ +_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on November 01, 2018._ [npmv-url]: https://www.npmjs.com/package/docks diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 79653b3..0000000 --- a/docs/API.md +++ /dev/null @@ -1,201 +0,0 @@ -_Generated using [docks](http://npm.im/docks)._ - - -### [src/index.js](/src/index.js) - -#### [docks](/src/index.js#L47) -Constructor that gives you methods. - -**Returns** -- `Object` instance of `Docks` - -#### [.use](/src/index.js#L79) -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/](/src/plugins) folder to see the built-in ones. - -**Params** -- `plugin` **{Function}** with signature like `(docks) => (comment) => {}` - -**Returns** -- `Object` instance of `Docks` - -**Examples** -```javascript -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](/src/index.js#L112) -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` an array with `Comment` objects. - -**Examples** -```javascript -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](/src/plugins/render.js) - -#### [.renderFileSync](/src/plugins/render.js#L50) -Render single `fp` file to a documentation string. - -**Params** -- `fp` **{string}** absolute filepath to file to look for doc comments. - -**Returns** -- `string` - -**Examples** -```javascript -const app = docks(); -const output = app.renderFileSync('path/to/source/file/with/comments'); -console.log(output); -``` - -#### [.renderFile](/src/plugins/render.js#L70) -Render single `fp` file to a documentation string, asynchronously. - -**Params** -- `fp` **{string}** absolute file path to look for doc comments. - -**Returns** -- `Promise` - -**Examples** -```javascript -const app = docks(); -app.renderFile('path/to/source/file/with/comments').then((output) => { - console.log(output); -}); -``` - -#### [.renderTextSync](/src/plugins/render.js#L95) -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** -```javascript -const app = docks(); - -const comments = app.parse('some string with block comments'); -const output = app.renderTextSync(comments); -console.log(output); -``` - -#### [.renderText](/src/plugins/render.js#L116) -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` - -**Examples** -```javascript -const app = docks(); - -const comments = app.parse('some string with block comments'); -app.renderText(comments).then((output) => { - console.log(output); -}); -``` - -#### [.renderSync](/src/plugins/render.js#L140) -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** -```javascript -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](/src/plugins/render.js#L170) -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` - -**Examples** -```javascript -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); -}); -``` - - - diff --git a/package.json b/package.json index 7092e1c..29743d1 100644 --- a/package.json +++ b/package.json @@ -4,14 +4,14 @@ "license": "Apache-2.0", "licenseStart": "2018", "scripts": { - "predocs": "rm -rf docs && yarn build", - "docs": "node dist/cli.js 'src/**/*' --outfile docs/API.md && verb", + "predocs": "yarn build", + "docs": "node dist/cli.js && verb", "lint": "eslint src test --fix --format codeframe", "test": "nyc --require esm asia", "prebuild": "rm -rf dist && mkdir dist", "build": "ascjs src dist", "commit-dry": "git status --porcelain && git add -A && gitcommit -sS", - "precommit": "yarn lint && yarn test", + "precommit": "yarn docs && yarn lint && yarn test", "commit": "yarn commit-dry", "prepublishOnly": "yarn build" }, diff --git a/src/cli.js b/src/cli.js index bee4b57..a2a8067 100644 --- a/src/cli.js +++ b/src/cli.js @@ -16,18 +16,41 @@ const app = docks(); /* eslint-disable promise/prefer-await-to-callbacks */ -fastGlob(argv._, { ...argv, absolute: true }) +const readFile = util.promisify(fs.readFile); +const writeFile = util.promisify(fs.writeFile); + +const inputFiles = argv._.length > 0 ? argv._ : 'src/**/*.{js,jsx,ts,tsx}'; + +fastGlob(inputFiles, { ...argv, absolute: true }) .then((files) => app.render(files)) - .then(async (content) => { + .then(async (apiContent) => { const outfile = argv.outfile ? path.resolve(argv.outfile) - : path.resolve('docs', 'README.md'); - - const dirname = path.dirname(outfile); - await util.promisify(mkdirp)(dirname); + : path.resolve('README.md'); const promo = '_Generated using [docks](http://npm.im/docks)._'; - return util.promisify(fs.writeFile)(outfile, `${promo}\n${content}`); + const docksStart = ''; + const docksEnd = ''; + const content = `${docksStart}\n${promo}${apiContent}\n${docksEnd}`; + + if (fs.existsSync(outfile)) { + const fileContent = await readFile(outfile, 'utf-8'); + + if (fileContent.includes(docksStart) && fileContent.includes(docksEnd)) { + const idxStart = fileContent.indexOf(docksStart); + const idxEnd = fileContent.indexOf(docksEnd); + const apiPart = fileContent.substring(idxStart, idxEnd); + const newContent = fileContent.replace(apiPart, content); + return writeFile(outfile, newContent); + } + const msg = `Outfile should contain placeholders or not exist.`; + throw new Error(msg); + } else { + const dir = path.dirname(outfile); + await util.promisify(mkdirp)(dir); + + return writeFile(outfile, content); + } }) .catch((err) => { console.error(err.stack);