From 52dd2512d22052d901951dd3ad0580cb710600b6 Mon Sep 17 00:00:00 2001 From: Robert Haritonov Date: Mon, 16 Nov 2015 21:44:56 +0100 Subject: [PATCH] make plugin configurable, improve component path resolving --- README.md | 71 ++++++++++++++++++++++++++++++++-------- core/middleware/index.js | 33 +++++++++---------- core/templates/props.ejs | 34 +++++++++---------- package.json | 5 +-- 4 files changed, 93 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index d6eaeaf..e66ddbc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# SourceJS auto React doc builder middleware. +# SourceJS Auto React Doc Builder Middleware -[react-docgen](https://github.com/reactjs/react-docgen) integration plugin, renders React components information into [SourceJS](http://sourcejs.com) Spec page. +[react-docgen](https://github.com/reactjs/react-docgen) integration plugin, renders React components information into [SourceJS](http://sourcejs.com) Spec page. Compatible with [SourceJS](http://sourcejs.com) 0.6.0+. @@ -16,16 +16,16 @@ After restarting your app, middleware will be loaded automatically. To disable i ## Usage -After installing the middleware, during spec load, plugin will try to find `/index.jsx` or `/src/index.jsx` file, analyze it and expose raw and rendered data objects. Data will be then available within [EJS Spec pre-rendering](http://sourcejs.com/docs/spec-helpers/#native-templating) (enabled by default). +After installing the middleware, during SourceJS Spec load plugin will try to find first `/*.jsx` file, analyze it and expose raw and rendered into HTML data objects. Data will be then available within [EJS Spec pre-rendering](http://sourcejs.com/docs/spec-helpers/#native-templating). -Insert these code snippets anywhere you want in your Spec file +Insert these code snippets anywhere you want in your Spec file: ```html

My Spec

Default Example

- +

<%- info.__docGenRaw.description %>

<%- info.__docGenHTML %> @@ -34,13 +34,30 @@ Insert these code snippets anywhere you want in your Spec file
``` -Other custom Spec file syntax with [sourcejs-react](https://github.com/szarouski/sourcejs-react) and [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) plugins is also supported. + # My Spec + + ## Default Example + + <%- info.__docGenRaw.description %> + + <%- info.__docGenHTML %> + + ```example + code + ``` -Check usage examples in [react-styleguide-example](https://github.com/sourcejs/react-styleguide-example). +Other custom Spec file syntax options like [sourcejs-react](https://github.com/szarouski/sourcejs-react) and [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) plugins are also supported. -### Define custom path to JSX file +Check usage examples in [react-styleguide-example](https://github.com/sourcejs/react-styleguide-example) and [react-styleguidist-example](https://github.com/sourcejs/react-styleguidist-example). -Using `info.json`, it's possible to define custom path to React component, apart from default `src/index.jsx`: +### EJS exposed data + +* **info.__docGenRaw** - raw JSON from react-docgen +* **info.__docGenHTML** - rendered table with properties + +## Configuration + +Using Spec's `info.json` file, it's possible to define custom path to React component: ``` { @@ -49,14 +66,40 @@ Using `info.json`, it's possible to define custom path to React component, apart } ``` -### Exposed Data +Or overriding global plugin configuration: -* **info.__docGenRaw** - raw JSON from react-docgen -* **info.__docGenHTML** - rendered table with properties +```javascript +module.exports = { + plugins: { + reactDocgen: { + componentPath: 'custom/path/index.jsx', + } + } +}; +``` + +See other configuration options below. + +### enabled + +Default: true +Type: _boolean_ + + +Set `false` to disable middleware. + +### componentPath + +Default: '*.jsx' +Type: _string_ + +Define custom path to component entry file. Accepts [glob](https://github.com/isaacs/node-glob) string, which will be resolved relatively to spec path (takes only first found file). + +## TODO: -## TODO +* Add auto-append option -* Add more configuration options +Pull request highly welcome! ## Other SourceJS Middlewares diff --git a/core/middleware/index.js b/core/middleware/index.js index 02ddabf..fb632a1 100644 --- a/core/middleware/index.js +++ b/core/middleware/index.js @@ -2,17 +2,21 @@ var reactDocgen = require('react-docgen'); var path = require('path'); var fs = require('fs'); var ejs = require('ejs'); +var glob = require("glob"); var specUtils = require(path.join(global.pathToApp,'core/lib/specUtils')); var currentDir = path.dirname(__filename); +var sourceJSUtils = require(path.join(global.pathToApp, 'core/lib/utils')); // Module configuration var globalConfig = global.opts.plugins && global.opts.plugins.reactDocgen ? global.opts.plugins.reactDocgen : {}; var config = { enabled: true, + componentPath: '*.jsx', // Public object is exposed to Front-end via options API. public: {} }; +sourceJSUtils.extendOptions(config, globalConfig); /* * @param {object} req - Request object @@ -27,41 +31,36 @@ var processRequest = function (req, res, next) { // Check if request is targeting Spec if (req.specData && req.specData.renderedHtml) { - var componentInfo = {}; + var componentDocs = {}; var error = false; var specPath = specUtils.getFullPathToSpec(req.path); - var componentPath = path.join(specPath, 'src/index.jsx'); - var componentPathAlt = path.join(specPath, 'index.jsx'); - var componentPathExists = fs.existsSync(componentPath); - var componentPathAltExists = fs.existsSync(componentPathAlt); - var componentPathToUse; + var componentPathToUse = req.specData.info.main || config.componentPath; - if (!(componentPathExists || componentPathAltExists)) { + var componentFilePath = glob.sync(componentPathToUse, { + cwd: specPath, + realpath: true + })[0]; + + if (!fs.existsSync(componentFilePath)) { next(); return; } - if (req.specData.info.main && fs.existsSync(path.join(specPath, req.specData.info.main))) { - componentPathToUse = path.join(specPath, req.specData.info.main); - } else { - componentPathToUse = fs.existsSync(componentPath) ? componentPath : componentPathAlt; - } - - var componentContent = fs.readFileSync(componentPathToUse, 'utf-8'); + var componentContent = fs.readFileSync(componentFilePath, 'utf-8'); var propsTpl = fs.readFileSync(path.join(currentDir, '../templates/props.ejs'), 'utf-8'); try { - componentInfo = reactDocgen.parse(componentContent); + componentDocs = reactDocgen.parse(componentContent); } catch(e) { error = true; console.warn('sourcejs-react-docgen: error generating component doc', e); } - req.specData.info.__docGenRaw = componentInfo; + req.specData.info.__docGenRaw = componentDocs; if (!error) { try { - req.specData.info.__docGenHTML = ejs.render(propsTpl, componentInfo); + req.specData.info.__docGenHTML = ejs.render(propsTpl, componentDocs); } catch(e) { console.warn('sourcejs-react-docgen: error rendering docgen props', e); } diff --git a/core/templates/props.ejs b/core/templates/props.ejs index 8f33450..161e3a2 100644 --- a/core/templates/props.ejs +++ b/core/templates/props.ejs @@ -1,23 +1,23 @@ <% if (typeof props !== 'undefined') { %> - +
+ + + + + + + + <% for(var key in props) { %> + <% var val = props[key] %> - - - - - + + + + + - <% for(var key in props) { %> - <% var val = props[key] %> - - - - - - - - <% } %> -
Property nameTypeRequiredDefault valueDescription
Property nameTypeRequiredDefault valueDescription<%- key %><%- val.type ? val.type.name : '-' %><%- val.required %><%- val.defaultValue ? val.defaultValue.value.replace(/'/g, '').replace(/"/g, '') : '-' %><%- val.description %>
<%- key %><%- val.type.name %><%- val.required %><%- val.defaultValue.value %><%- val.description %>
+ <% } %> + <% } else { %> No props defined in component. <% } %> \ No newline at end of file diff --git a/package.json b/package.json index 93c70e5..ae84106 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sourcejs-react-docgen", - "version": "0.2.0", + "version": "0.3.0", "description": "SourceJS auto React doc builder middleware.", "repository": { "type": "git", @@ -9,6 +9,7 @@ "homepage": "https://github.com/sourcejs/sourcejs-react-docgen", "dependencies": { "ejs": "^2.3.4", - "react-docgen": "^2.2.0" + "glob": "^6.0.1", + "react-docgen": "^2.4.0" } }