https://github.com/FormidableLabs/ecology
Documentation generator for collections of react components.
https://github.com/FormidableLabs/ecology
Last synced: 20 days ago
JSON representation
Documentation generator for collections of react components.
- Host: GitHub
- URL: https://github.com/FormidableLabs/ecology
- Owner: FormidableLabs
- License: mit
- Archived: true
- Created: 2015-10-01T03:55:19.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2022-02-11T05:47:56.000Z (over 4 years ago)
- Last Synced: 2025-08-09T05:22:27.226Z (11 months ago)
- Language: JavaScript
- Size: 15.8 MB
- Stars: 107
- Watchers: 56
- Forks: 13
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-github-projects - ecology - Documentation generator for collections of react components. ⭐106 `JavaScript` (📦 Legacy & Inactive Projects)
README
[![Travis Status][trav_img]][trav_site]
[![Maintenance Status][maintenance-image]](#maintenance-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](demo) for a complete example:
```sh
# 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](https://github.com/reactjs/react-docgen#example) 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`.
```jsx
// createClass() example
const MyComponent = React.createClass({
propTypes: {
/**
* A test prop
* @examples "Test", "More Test", "Yep"
*/
testProp: React.PropTypes.string
},
render() {
return
Sample;
}
});
// 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
Sample;
}
}
```
## 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`
```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 (
);
}
}
ReactDOM.render(, 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
```
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 (
);
}
})
ReactDOM.render(, 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`
```html
// index.html
// Minimal example. See `demo/index.html` for an example with fallbacks for older browsers.
Ecology Demo
```
4. Create `docs/webpack.config.js`
```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`
```sh
$ 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`](https://github.com/reactjs/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](https://github.com/chjj/marked) renderer methods. ex `link: function(href, title, text) {return href}`. A list of available elements is [available here](https://github.com/chjj/marked#renderer). *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](DEVELOPMENT.md)
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md)
## Maintenance Status
**Archived:** This project is no longer maintained by Formidable. We are no longer responding to issues or pull requests unless they relate to security concerns. We encourage interested developers to fork this project and make it their own!
[maintenance-image]: https://img.shields.io/badge/maintenance-archived-red.svg
[trav_img]: https://api.travis-ci.org/FormidableLabs/ecology.svg
[trav_site]: https://travis-ci.org/FormidableLabs/ecology