ecology

v1.7.0

Published

a year ago

React Component

Downloads

316

Ecology

Description

Ecology allows you to write markdown documentation for React components that includes interactive playground sections and auto-generated propType specifications.

See the demo app for a complete example:

# Runs the demo component documentation dev-server
# and open it in your default browser.

$ npm run dev && npm run open-demo

Component PropType Documentation

Your component should be created using React.createClass() or class Foo extends React.Component.
Your component should define propTypes in the createClass object literal or as a static property of the class.
Your component may define default props as getDefaultProps method (React.createClass() syntax), or as a defaultProps static property of the class.
You should add a JSDoc-style comment block for each prop, with a description and optional @examples.

// createClass() example
const MyComponent = React.createClass({
  propTypes: {
    /**
     * A test prop
     * @examples "Test", "More Test", "Yep"
     */
    testProp: React.PropTypes.string
  },

  render() {
    return <div>Sample</div>;
  }
});

// class declaration example
// NOTE: Requires `babel-preset-stage-1`
class MyComponent extends React.Component {
  static propTypes = {
    /**
     * A test prop
     * @examples "Test", "More Test", "Yep"
     */
    testProp: React.PropTypes.string
  };

  render() {
    return <div>Sample</div>;
  }
}

Writing Your Component Documentation

Create these files according to the below examples:

docs/docs.jsx
docs/ecology.md
docs/index.html
docs/webpack.config.js

Create docs/docs.jsx

// docs.jsx

import React from "react";
import ReactDOM from "react-dom";
import Ecology from "ecology";
import * as docgen from "react-docgen";

import MyComponent from "../src/my-component";

class Docs extends React.Component {
  render() {
    return (
      <div className="demo">
        <Ecology
          // This loads up your markdown documentation.
          overview={require("!!raw!./ecology.md")}

          // This loads up your component source so Ecology can inject the `propType` table.
          source={docgen.parse(require("!!raw!../src/my-component"))}

          // The `scope` prop is used by Component Playground to render live code snippets.
          // It needs React, ReactDOM, and your component.
          // See https://github.com/FormidableLabs/component-playground#scope
          scope={{ React, ReactDOM, MyComponent }}
          playgroundtheme="blackboard"
        />
      </div>
    );
  }
}

ReactDOM.render(<Docs/>, document.getElementById("content"));

Create docs/ecology.md:

 // ecology.md

 Interactive Docs for My Component
 =================================

 PlayGround
 ----------

 A `playground` triple-backtick snippet will render your component for you. This is useful for quick interactive component demos without the need to add boilerplate.

 ```playground
 <MyComponent />
 ```

 NoRender Playground
 -------------------

 A `playground_norender` triple-backtick snippet will not do automatic rendering of your component; you have to manually call `ReactDom.render`. Useful for examples of using your component in context.

 ```playground_norender
 var App = React.createClass({
   render() {
       return (
       <MyComponent />
       );
     }
 })

 ReactDOM.render(<App/>, mountNode);
 ```

 ## Prop Types

 Ecology will inject a `propTypes` table at the bottom of your component docs. This is generated from the component `propTypes` definition, and takes into account JSDoc style comments for each `propType`

Create docs/index.html

// index.html
// Minimal example. See `demo/index.html` for an example with fallbacks for older browsers.

<!doctype html>
<html>
  <head>
    <title>Ecology Demo</title>
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/codemirror.min.css"/>
    <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/theme/blackboard.min.css"/>
  </head>
  <body>
    <div id="content"></div>
    <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/codemirror.min.js"></script>
    <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/mode/javascript/javascript.min.js"></script>
    <script type="text/javascript" src="main.js"></script>
  </body>
</html>

Create docs/webpack.config.js

// webpack.config.js
module.exports = {
  devServer: {
    contentBase: __dirname,
    noInfo: false
  },
  output: {
    path: __dirname,
    filename: "main.js",
    publicPath: "/"
  },
  devtool: "source-map",
  entry: {
    app: ["./docs/docs.jsx"]
  },
  resolve: {
    extensions: ["", ".js", ".jsx"]
  },
  module: {
    loaders: [
      {
        test: /\.jsx?$/,
        loader: "babel-loader",
        query: {
          presets: ["es2015", "react"]
        },
        exclude: /node_modules/
      }
    ]
  }
};

Install dependencies and run webpack-dev-server

$ npm install -S babel babel-core babel-preset-es2015 babel-preset-react babel-loader raw-loader ecology react react-dom react-docgen webpack webpack-dev-server
$ node_modules/.bin/webpack-dev-server --port 3000 --config docs/webpack.config.js --watch --content-base docs

Required Props

Overview - Markdown documentation file in raw/string format
Source - React class source file in parsed react-docgen format
Scope - Scope for component-playground components. Used by Component Playground to render live code snippets. It needs React, ReactDOM, and your component.

Optional Props

customRenderers - Pass an object with custom marked renderer methods. ex link: function(href, title, text) {return href}. A list of available elements is available here. Note: Method must return a string.
exportGist - Adds a button to export the playground source as an anonymous Gist on Github. Enabling this adds a Toolbar component to the markup, with a Button-GistExport component and Toolbar-Message area for displaying error messages.
copyToClipboard - Adds a button to copy the playground source to the clipboard. Enabling this adds a Toolbar component to the markup, with a Button-Clipboard component.

Deploying Your Docs

Help us write this documentation! https://github.com/FormidableLabs/ecology/issues/20

Development

Please see DEVELOPMENT

Contributing

Please see CONTRIBUTING

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme