Have ideas to improve npm?Join in the discussion! »

    ecology

    1.7.0 • Public • Published

    Travis Status

    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

    1. Your component should be created using React.createClass() or class Foo extends React.Component.
    2. Your component should define propTypes in the createClass object literal or as a static property of the class.
    3. Your component may define default props as getDefaultProps method (React.createClass() syntax), or as a defaultProps static property of the class.
    4. 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
    1. 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 `propTypetable.
              source={docgen.parse(require("!!raw!../src/my-component"))}
     
              // The `scopeprop is used by Component Playground to render live code snippets.
              // It needs ReactReactDOMand your component.
              // See https://github.com/FormidableLabs/component-playground#scope
              scope={{ React, ReactDOM, MyComponent }}
              playgroundtheme="blackboard"
            />
          </div>
        );
      }
    }
     
    ReactDOM.render(<Docs/>, document.getElementById("content"));
    1. 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`
      
    2. 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>
    1. 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/
          }
        ]
      }
    };
    1. 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

    Keywords

    none

    Install

    npm i ecology

    DownloadsWeekly Downloads

    59

    Version

    1.7.0

    License

    MIT

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar