FormidableLabs/ecology

Name: ecology

Owner: Formidable

Description: Documentation generator for collections of react components.

Created: 2015-10-01 03:55:19.0

Updated: 2018-01-02 20:17:09.0

Pushed: 2017-09-21 20:39:16.0

Homepage: null

Size: 16201

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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:

ns the demo component documentation dev-server
d open it in your default browser.

m 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.

   reateClass() example
   t MyComponent = React.createClass({
   Types: {
   *
    A test prop
    @examples "Test", "More Test", "Yep"
   /
   stProp: React.PropTypes.string
   
   
   er() {
   turn <div>Sample</div>;
   
   
   
   lass declaration example
   OTE: Requires `babel-preset-stage-1`
   s MyComponent extends React.Component {
   ic propTypes = {
   *
    A test prop
    @examples "Test", "More Test", "Yep"
   /
   stProp: React.PropTypes.string
   
   
   er() {
   turn <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

  ocs.jsx
  
  rt React from "react";
  rt ReactDOM from "react-dom";
  rt Ecology from "ecology";
  rt * as docgen from "react-docgen";
  
  rt MyComponent from "../src/my-component";
  
  s Docs extends React.Component {
  er() {
  turn (
  <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>
  
  
  
  
  tDOM.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

  ndex.html
  inimal example. See `demo/index.html` for an example with fallbacks for older browsers.
  
  ctype html>
  l>
  d>
  itle>Ecology Demo</title>
  ink rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/codemirror.min.css"/>
  ink rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/theme/blackboard.min.css"/>
  ad>
  y>
  iv id="content"></div>
  cript type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/codemirror.min.js"></script>
  cript type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/mode/javascript/javascript.min.js"></script>
  cript type="text/javascript" src="main.js"></script>
  dy>
  ml>
  

• Create docs/webpack.config.js

  ebpack.config.js
  le.exports = {
  erver: {
  ntentBase: __dirname,
  Info: false
  
  ut: {
  th: __dirname,
  lename: "main.js",
  blicPath: "/"
  
  ool: "source-map",
  y: {
  p: ["./docs/docs.jsx"]
  
  lve: {
  tensions: ["", ".js", ".jsx"]
  
  le: {
  aders: [
  {
    test: /\.jsx?$/,
    loader: "babel-loader",
    query: {
      presets: ["es2015", "react"]
    },
    exclude: /node_modules/
  }
  
  
  
  

• Install dependencies and run webpack-dev-server

  m 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
  de_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