diff --git a/.babelrc b/.babelrc new file mode 100644 index 0000000..07e0334 --- /dev/null +++ b/.babelrc @@ -0,0 +1,7 @@ +{ + "ignore": [ + "__tests__", + "__mocks__" + ], + "presets": [ "es2015", "es2016" ] +} diff --git a/.gitignore b/.gitignore index 1e80f67..9c7cdc3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ -# react-doc-generator +# react-asciidoc-generator dist +node # Logs logs @@ -38,3 +39,8 @@ jspm_packages # Optional REPL history .node_repl_history + +#Other +/cmd +/node +pom.xml diff --git a/.npmignore b/.npmignore index bc9b631..9951865 100644 --- a/.npmignore +++ b/.npmignore @@ -1,4 +1,4 @@ -# react-doc-generator +# react-asciidoc-generator # Logs demo logs @@ -30,6 +30,7 @@ build/Release # Dependency directories node_modules +node jspm_packages # Optional npm cache directory diff --git a/DOCUMENTATION.ADOC b/DOCUMENTATION.ADOC new file mode 100644 index 0000000..45c5d73 --- /dev/null +++ b/DOCUMENTATION.ADOC @@ -0,0 +1,67 @@ += Components + +:numbered: + + +== File: *..\react-doc-generator-test\test\ExampleComponent.js* + +=== General component description. + +fdgdfgdf gfdgfdg fdgfdgdfg +gdfgfdgdfg dfgdfgfdg dfg df getDefaultPropsg fdgfd +gfdgfdgdfgfdg. + + +Example: +```html + +``` + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no|42|Description of prop "foo". +|bar|custom|no|21|Description of prop "bar" (a custom validation function). +|baz|union|no|| + +|=== + + + +== File: *..\react-doc-generator-test\test\inside\OtherExampleComponent.js* + +=== General component description. + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no|10000099999|Description of prop "foo". +|bar|custom|no||Description of prop "bar" (a custom validation function). +|baz|union|no|| +|onExit|func|no|<See the source code>| + +|=== + +=== DUPA + +General another component description. +Blah blah blah... +fdfdfsdf +fdsfsd + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no||Description of prop "foo". +|bar|custom|no||Description of prop "bar" (a custom validation function). +|baz|union|no|| + +|=== + + diff --git a/LICENSE b/LICENSE index 924d61e..af05be8 100644 --- a/LICENSE +++ b/LICENSE @@ -19,3 +19,25 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +MIT License + +Copyright (c) 2017 Frode Carlsen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 9abb3ff..600b281 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,47 @@ # React DOC Generator -[![npm version](https://img.shields.io/npm/v/react-doc-generator.svg?style=flat-square)](https://www.npmjs.com/package/react-doc-generator) -[![dependency status](https://img.shields.io/david/marborkowski/react-doc-generator.svg?style=flat-square)](https://david-dm.org/marborkowski/react-doc-generator) -[![build status](https://img.shields.io/travis/marborkowski/react-doc-generator.svg?style=flat-square)](https://travis-ci.org/marborkowski/react-doc-generator) +[![npm version](https://img.shields.io/npm/v/react-asciidoc-generator.svg?style=flat-square)](https://www.npmjs.com/package/react-asciidoc-generator) +[![dependency status](https://img.shields.io/david/frode-carlsen/react-asciidoc-generator.svg?style=flat-square)](https://david-dm.org/frode-carlsen/react-asciidoc-generator) +[![build status](https://img.shields.io/travis/frode-carlsen/react-asciidoc-generator.svg?style=flat-square)](https://travis-ci.org/frode-carlsen/react-asciidoc-generator) +[![Known Vulnerabilities](https://snyk.io/test/github/frode-carlsen/react-asciidoc-generator/badge.svg?targetFile=package.json)](https://snyk.io/test/github/frode-carlsen/react-asciidoc-generator?targetFile=package.json) -Generate simple React components documentation in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). +This is a fork of [react-doc-generator](https://github.com/frode-carlsen/react-doc-generator) to provide additional features for asciidoc or custom templates. + +Generate simple React components documentation in either +* [Asciidoc](http://asciidoctor.org/docs/). +* [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). +* Any custom handlebar template ## Installation -`$ npm install -save-dev react-doc-generator` +`$ npm install -save-dev react-asciidoc-generator` ## Usage -Check every option runnig `react-doc-generator` with `--help` or `-h`: +Check every option running `react-asciidoc-generator` with `--help` or `-h`: ``` -$ react-doc-generator --help +$ react-asciidoc-generator --help -Usage: react-doc-generator [options] +Usage: react-asciidoc-generator [options] Options: -h, --help output usage information -V, --version output the version number -x, --extensions Include only these file extensions. Default: js,jsx + -f, --format Output format (asciiddoc|asciidoc) [asciidoc] -i, --ignore Folders to ignore. Default: node_modules,__tests__,__mocks__ - -e, --exclude-patterns Filename patterns to exclude. Default: [] + -e, --exclude-patterns Filename patterns to exclude (may be comma-separated list of regexp). Default: '.*\.spec.(jsx|js)' -t, --title [value]> Document title. Default: 'Components' - -o, --output Markdown file to write. Default: 'README.MD' + -o, --output Output file to write. Default (asciidoc): 'DOCUMENTATION.ADOC'. Default (markdown): 'DOCUMENTATION.MD' + --handlebar-template [path] Custom handlebar output template. Alternative to --format. ``` ### By the command line Example: -`$ react-doc-generator src -o DOCUMENTATION.md` +`$ react-asciidoc-generator src -o DOCUMENTATION.adoc ### NPM script @@ -44,7 +52,7 @@ In your `package.json` put: { // ... "scripts": { - "doc": "react-doc-generator ./app/components/custom -o DOCUMENTATION.md" + "doc": "react-asciidoc-generator ./app/components/custom -o DOCUMENTATION.ADOC" } // ... } @@ -94,22 +102,26 @@ export class MyComponent extends React.Component { } ``` -Because [**react-doc-generator**](https://github.com/marborkowski/react-doc-generator) uses [**react-docgen**](https://github.com/reactjs/react-docgen) library, you can [follow other examples here](https://github.com/reactjs/react-docgen). +Because [**react-asciidoc-generator**](https://github.com/frode-carlsen/react-asciidoc-generator) uses [**react-docgen**](https://github.com/reactjs/react-docgen) library, you can [follow other examples here](https://github.com/reactjs/react-docgen). ## Demo - * [Example output](https://github.com/marborkowski/react-doc-generator/blob/master/demo/DOCUMENTATION.md) + * [Example output](https://github.com/frode-carlsen/react-asciidoc-generator/blob/master/demo/DOCUMENTATION.adoc) ## Terminal This is an example of what you'll see in your terminal. -![Terminal](https://raw.githubusercontent.com/marborkowski/react-doc-generator/master/demo/terminal.png) +![Terminal](https://raw.githubusercontent.com/frode-carlsen/react-asciidoc-generator/master/demo/terminal.png) + +### Acknowledgemens + +Forked from original module 'react-doc-generator' by Marcin Borowski (https://github.com/marborkowski/react-doc-generator) -### License +### Licenses MIT License -Copyright (c) 2017 Marcin Borkowski () +Copyright (c) 2017 Marcin Borkowski () Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights diff --git a/doc.adoc b/doc.adoc new file mode 100644 index 0000000..79e07d4 --- /dev/null +++ b/doc.adoc @@ -0,0 +1,67 @@ += Components + +:numbered: + + +== File: ** + +=== General component description. + +fdgdfgdf gfdgfdg fdgfdgdfg +gdfgfdgdfg dfgdfgfdg dfg df getDefaultPropsg fdgfd +gfdgfdgdfgfdg. + + +Example: +```html + +``` + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no|42|Description of prop "foo". +|bar|custom|no|21|Description of prop "bar" (a custom validation function). +|baz|union|no|| + +|=== + + + +== File: ** + +=== General component description. + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no|10000099999|Description of prop "foo". +|bar|custom|no||Description of prop "bar" (a custom validation function). +|baz|union|no|| +|onExit|func|no|<See the source code>| + +|=== + +=== DUPA + +General another component description. +Blah blah blah... +fdfdfsdf +fdsfsd + + + +[options="header"] +|=== +|Property | Type | Required | Default value | Description +|foo|number|no||Description of prop "foo". +|bar|custom|no||Description of prop "bar" (a custom validation function). +|baz|union|no|| + +|=== + + diff --git a/package.json b/package.json index 2fd408c..45986f8 100644 --- a/package.json +++ b/package.json @@ -1,29 +1,34 @@ { - "name": "react-doc-generator", - "version": "1.2.5", - "description": "Generate a simple React Component documentation in Markdown.", + "name": "react-asciidoc-generator", + "version": "1.5.8", + "description": "Generate a simple React Component documentation in Asciidoc, Markdown, or custom template", "main": "dist/index.js", "bin": { - "react-doc-generator": "dist/react-doc-generator.js" + "react-asciidoc-generator": "dist/react-asciidoc-generator.js" }, "scripts": { "lint": "eslint src", - "transpile": "babel src -D -d dist --ignore '__tests__, __mocks__'", - "watch": "babel src -D -d dist --ignore '__tests__,__mocks__' --watch", + "transpile": "babel src -D -d dist", + "build": "babel src -D -d dist", + "watch": "babel src -D -d dist --watch", "pretest": "npm run transpile", "preversion": "npm run lint", + "prepublish": "babel src -D -d dist", "test": "jest" }, "repository": { "type": "git", - "url": "git+https://github.com/marborkowski/react-doc-generator.git" + "url": "git+https://github.com/frode-carlsen/react-asciidoc-generator.git" }, - "author": "Marcin Borkowski", + "author": "Frode Carlsen", + "contributors": [ + "Marcin Borkowski (https://github.com/marborkowski/react-doc-generator)" + ], "license": "MIT", "bugs": { - "url": "https://github.com/marborkowski/react-doc-generator/issues" + "url": "https://github.com/frode-carlsen/react-asciidoc-generator/issues" }, - "homepage": "https://github.com/marborkowski/react-doc-generator#readme", + "homepage": "https://github.com/frode-carlsen/react-asciidoc-generator#readme", "keywords": [ "react", "react-docgen", @@ -51,13 +56,15 @@ "node-dir": "^0.1.16", "react": "^15.4.2", "react-docgen": "^2.13.0", - "react-dom": "^15.4.2" + "react-dom": "^16.0.1" }, "devDependencies": { "babel-cli": "^6.23.0", "babel-eslint": "^7.1.1", "babel-jest": "^19.0.0", "babel-preset-env": "^1.2.0", + "babel-preset-es2015": "^6.24.1", + "babel-preset-es2016": "^6.24.1", "eslint": "^3.17.0", "eslint-config-react-app": "^0.5.2", "eslint-plugin-flowtype": "^2.30.0", diff --git a/src/__tests__/react-doc-generator.test.js b/src/__tests__/react-asciidoc-generator.test.js similarity index 100% rename from src/__tests__/react-doc-generator.test.js rename to src/__tests__/react-asciidoc-generator.test.js diff --git a/src/lib/command.js b/src/lib/command.js index 92206c9..c1b0eca 100644 --- a/src/lib/command.js +++ b/src/lib/command.js @@ -13,9 +13,11 @@ export default (function Command () { .usage(` [options]`) .option('-x, --extensions ', 'Include only these file extensions. Default: js,jsx', list, ['js', 'jsx']) .option('-i, --ignore ', 'Folders to ignore. Default: node_modules,__tests__,__mocks__', list, ['node_modules', '__tests__', '__mocks__']) - .option('-e, --exclude-patterns ', 'Filename patterns to exclude. Default: []', list, []) + .option('-e, --exclude-patterns ', 'Filename patterns to exclude. Default: []', list, ['.*\.spec.(jsx|js)' ]) + .option('-f, --format ', 'Output format (markdown|asciiddoc) [asciidoc]') .option('-t, --title [value]', 'Document title. Default: \'Components\'', 'Components') - .option('-o, --output ', 'Markdown file to write. Default: \'DOCUMENTATION.MD\'', 'DOCUMENTATION.MD') + .option('-o, --output ', 'Output file to write. Default (asciidoc): \'DOCUMENTATION.ADOC\'') + .option('--handlebar-template [path]', 'Custom handlebar output template. Alternative to --format.') .parse(process.argv); diff --git a/src/react-asciidoc-generator.js b/src/react-asciidoc-generator.js new file mode 100644 index 0000000..35676f8 --- /dev/null +++ b/src/react-asciidoc-generator.js @@ -0,0 +1,147 @@ +#!/usr/bin/env node + +import { parse, resolver } from 'react-docgen'; +import fs from 'fs'; +import path from 'path'; +import Command from './lib/command.js'; +import { readFiles } from 'node-dir'; +import Handlebars from 'handlebars'; +import Colors from 'colors'; +import Table from 'cli-table'; + +const pkg = require('../package.json'); +const table = new Table({ + head: [ + Colors.cyan('Path'), + Colors.cyan('Components'), + Colors.cyan('Status') + ] +}); + +Handlebars.registerHelper('inc', (value, options) => { + return parseInt(value, 10) + 1; +}); + +function getOutputConfig() { + const result = { + outputFile: Command.output || 'DOCUMENTATION.TXT', + template: null, + format: Command.format || 'asciidoc' + }; + + if(['markdown', 'asciidoc'].indexOf(result.format) === -1){ + throw 'Invalid format: ' + result.format + ', expected one of (asciidoc|markdown)'; + } + + result.template = Command.handlebarTemplate || path.join(__dirname, 'template-' + result.format + '.handlebars'); + + if(!Command.output && !Command.handlebarTemplate){ + if(result.format == 'asciidoc') { + result.outputFile = 'DOCUMENTATION.ADOC'; + } else if (result.format == 'markdown') { + result.outputFile = 'DOCUMENTATION.MD'; + } + } + + return result; +} + +const templateData = { + files: [], + version: pkg.version, + documentTitle: Command.title +}; + + +if (Command.args.length !== 1) { + console.log(`${Colors.red('Please specify as the first argument!')}`); + Command.help(); +} else { + + let outputConfig = getOutputConfig(); + + const output = fs.createWriteStream(outputConfig.outputFile); + const template = Handlebars.compile(`${fs.readFileSync(outputConfig.template)}`); + + const excludeFilePatterns = new RegExp('^.*(?:' + Command.excludePatterns.join('|') + ')$'); + const rootDir = path.normalize(Command.args[0]); + readFiles( + rootDir, + { + match: new RegExp('\\.(?:' + Command.extensions.join('|') + ')$'), + excludeDir: Command.ignore, + }, + (err, content, filename, next) => { + if (err) { + throw err; + } + + if(!filename.match(excludeFilePatterns)) { + var abbrevFilename = filename.replace(rootDir, ''); + try { + let components = parse(content, resolver.findAllExportedComponentDefinitions); + components = components.map(component => { + if (component.description && !component.displayName) { + component.title = component.description.match(/^(.*)$/m)[0]; + if (component.description.split('\n').length > 1) { + component.description = component.description.replace(/[\w\W]+?\n+?/, ''); + component.description = component.description.replace(/(\n)/gm, ' \n'); + } else { + component.description = null; + } + } else { + component.title = component.displayName; + } + + if (component.description) { + component.description = `${component.description} \n\n`; + } + + // validate default values + if (component.props) { + Object.keys(component.props).forEach(key => { + let obj = component.props[key]; + if (obj.defaultValue) { + if ((/[^\w\s.&:\-+*,!@%$]+/igm).test(obj.defaultValue.value)) { + obj.defaultValue.value = ''; + } + } + }); + } + + return component; + }); + templateData.files.push({ abbrevFilename, components }); + table.push([ + abbrevFilename, + components.length, + Colors.green(`OK.`) + ]); + } catch (e) { + table.push([ + abbrevFilename, + 0, + Colors.red(`You have to export at least one valid React Class!`) + ]); + } + } + next(); + }, + err => { + if (err) { + throw err; + } + + if (templateData.files.length === 0) { + let extensions = Command.extensions.map(ext => { + return `\`*.${ext}\``; + }); + console.log(`${Colors.bold.yellow('Warning:')} ${Colors.yellow(`Could not find any files matching the file type: ${extensions.join(' OR ')}`)}\n`); + } else { + console.log(`${table.toString()}\n\n`); + } + + output.write(template(templateData)); + } + ); +} diff --git a/src/react-doc-generator.js b/src/react-doc-generator.js deleted file mode 100644 index 9039199..0000000 --- a/src/react-doc-generator.js +++ /dev/null @@ -1,121 +0,0 @@ -#!/usr/bin/env node - -import { parse, resolver } from 'react-docgen'; -import fs from 'fs'; -import path from 'path'; -import Command from './lib/command.js'; -import { readFiles } from 'node-dir'; -import Handlebars from 'handlebars'; -import Colors from 'colors'; -import Table from 'cli-table'; - -const pkg = require('../package.json'); -const table = new Table({ - head: [ - Colors.cyan('Path'), - Colors.cyan('Components'), - Colors.cyan('Status') - ] -}); - -Handlebars.registerHelper('inc', (value, options) => { - return parseInt(value, 10) + 1; -}); - -console.log(Colors.white(`\n\nREACT DOC GENERATOR v${pkg.version}`)); -console.log(Colors.white(`by Marcin Borkowski `)); - - - -const output = fs.createWriteStream(Command.output); -const templateData = { - files: [], - version: pkg.version, - documentTitle: Command.title -}; - -const template = Handlebars.compile(`${fs.readFileSync(path.join(__dirname, 'template.handlebars'))}`); - -if (Command.args.length !== 1) { - console.log(`${Colors.red('Please specify as the first argument!')}`); - Command.help(); -} else { - readFiles( - Command.args[0], - { - match: new RegExp('\\.(?:' + Command.extensions.join('|') + ')$'), - exclude: Command.excludePatterns, - excludeDir: Command.ignore, - }, - (err, content, filename, next) => { - if (err) { - throw err; - } - - try { - let components = parse(content, resolver.findAllExportedComponentDefinitions); - components = components.map(component => { - if (component.description && !component.displayName) { - component.title = component.description.match(/^(.*)$/m)[0]; - if (component.description.split('\n').length > 1) { - component.description = component.description.replace(/[\w\W]+?\n+?/, ''); - component.description = component.description.replace(/(\n)/gm, ' \n'); - } else { - component.description = null; - } - } else { - component.title = component.displayName; - } - - if (component.description) { - component.description = `${component.description} \n\n`; - } - - // validate default values - if (component.props) { - Object.keys(component.props).forEach(key => { - let obj = component.props[key]; - if (obj.defaultValue) { - if ((/[^\w\s.&:\-+*,!@%$]+/igm).test(obj.defaultValue.value)) { - obj.defaultValue.value = ''; - } - } - }); - } - - return component; - }); - templateData.files.push({ filename, components }); - table.push([ - filename, - components.length, - Colors.green(`OK.`) - ]); - } catch (e) { - table.push([ - filename, - 0, - Colors.red(`You have to export at least one valid React Class!`) - ]); - } - - next(); - }, - err => { - if (err) { - throw err; - } - - if (templateData.files.length === 0) { - let extensions = Command.extensions.map(ext => { - return `\`*.${ext}\``; - }); - console.log(`${Colors.bold.yellow('Warning:')} ${Colors.yellow(`Could not find any files matching the file type: ${extensions.join(' OR ')}`)}\n`); - } else { - console.log(`${table.toString()}\n\n`); - } - - output.write(template(templateData)); - } - ); -} diff --git a/src/template-asciidoc.handlebars b/src/template-asciidoc.handlebars new file mode 100644 index 0000000..651ecb3 --- /dev/null +++ b/src/template-asciidoc.handlebars @@ -0,0 +1,29 @@ +{{#if documentTitle}} += {{documentTitle}} +{{/if}} + +:numbered: + +{{#each files}} + +== File: *{{filename}}* + +{{#each components}} +=== {{title}} + +{{{description}}} + +{{#if props}} +[options="header"] +|=== +|Property | Type | Required | Default value | Description +{{#each props}} +|{{@key}}|{{type.name}}|{{#if required}}yes{{else}}no{{/if}}|{{defaultValue.value}}|{{description}} +{{/each}} + +|=== +{{/if}} + +{{/each}} + +{{/each}} diff --git a/src/template.handlebars b/src/template-markdown.handlebars similarity index 100% rename from src/template.handlebars rename to src/template-markdown.handlebars