Documentation generator for collections of react components.
JavaScript CSS HTML
Latest commit 1221716 Oct 4, 2016 @ryan-roemer ryan-roemer * Replace `concurrently` with [`builder concurrent`](https://formidab…
…le.com/open-source/builder/#builder-concurrent) for more powerful + flexible `npm` script execution.

* Remove dependencies on `concurrently` is not actually used for `npm` scripts.
* Upgrade `builder` dependencies if already existing.
* Sort `dependencies` + `devDependencies` by key.

> This PR has been automatically opened by your friendly [`multibot`](https://github.com/FormidableLabs/multibot/). The transform code and documentation is available at: https://github.com/FormidableLabs/multibot-examples/tree/master/transforms/builder-concurrent
Permalink
Failed to load latest commit information.
demo pass the correct props Jul 18, 2016
dist
src fix linting Jul 20, 2016
test/client
.babelrc adding .babelrc Feb 29, 2016
.editorconfig initial commit Oct 1, 2015
.eslintignore initial commit Oct 1, 2015
.eslintrc-base initial commit Oct 1, 2015
.eslintrc-client initial commit Oct 1, 2015
.eslintrc-client-test initial commit Oct 1, 2015
.eslintrc-server initial commit Oct 1, 2015
.gitignore Merge pull request #25 from NogsMPLS/IntelliJGitIgnore Feb 29, 2016
.npmignore Ignore source-maps Feb 24, 2016
.travis.yml Build all branches with Travis Jan 13, 2016
CHANGELOG.md update CHANGELOG.md Aug 23, 2016
CONTRIBUTING.md Add Contributor Covenant Code of Conduct Aug 24, 2016
DEVELOPMENT.md Update DEVELOPMENT.md Feb 25, 2016
LICENSE.txt initial commit Oct 1, 2015
README.md
karma.conf.coverage.js initial commit Oct 1, 2015
karma.conf.dev.js
karma.conf.js initial commit Oct 1, 2015
package.json
webpack.config.coverage.js fix linting Feb 18, 2016
webpack.config.dev.js initial commit Oct 1, 2015
webpack.config.js fixing .json shenanigans May 17, 2016
webpack.config.test.js Add documentation for Ecology Jan 29, 2016

README.md

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 `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"));
  2. 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`
    
  3. 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>
  4. 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/
          }
        ]
      }
    };
  5. 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