ecology

React Component

1.7.0
latest
Source
npm

Version published: 7 years ago

Maintainers: 22

Created: 9 years ago

Source

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.

FAQs

What is ecology?

Is ecology well maintained?

Package last updated on 21 Sep 2017

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install