快速優雅的爲React組件生成文檔

在開發React組件時咱們一般須要處理2個問題：

1. 實例化這個組件以便調試

2. 爲這個組件編寫使用文檔以便更好的讓別人知道怎麼使用這個組件

最原始的方法莫過於開發時建一個頁面用於調試，開發完後再爲其手寫文檔。然而一個詳細的React組件文檔應該包括：

1. 爲各類使用場景編寫demo以及對應的說明，同時附上demo的源碼

2. 有demo能夠當場體驗而不是使用者要本身寫代碼後才能體驗這個組件

3. 它的屬性列表(propTypes)

4. 它的實例方法列表

若是你想作到以上估計得花上你一天的功夫，我但願能把精力放在開發更好的組件上剩下的能絕不費勁的優雅完成，因而我作了本文的主角Redemo。
Redemo是用來簡單優雅的完成以上問題讓你專一於開發本身的組件，剩下的一切它都爲你作好了。先看下Redemo爲組件生成文檔的效果圖或直接體驗部分實踐中的項目redemo文檔、imuix：

結構以下：

• 最上面是可當即體驗的組件demo，同時能夠用在開發過程當中調試組件

• 組件實例下是這個demo的說明，支持markdown

• 接下來是組件的屬性列表(propTypes)，支持markdown

• 最後是這個demo的源碼

爲你的組件生成這個你幾乎不用寫超過10行簡單的代碼更不用單獨爲組件寫文檔。假設你編寫了一個Button組件，讓咱們來爲Button組件編寫一個demo：

1. 經過npm i redemo 安裝 redemo

2. 寫下這些簡單的代碼

import Redemo from 'redemo';
import Demo from './demo';//爲一個使用場景實例化Button組件的demo源碼
// 使用docgen 從 Button 組件源碼裏分析出 propTypes
const docgen = require('!!docgen-loader!../button');
// 讀取爲Button組件編寫的demo的源碼
const code = require('!!raw-loader!../demo');
const doc = `爲這個demo作一些說明，支持*markdown*`
render(
<Redemo
  docgen={docgen}
  doc={doc}
  code={code}
>
  <Demo/>
</Redemo>
)

聰明的你大概會問以上代碼並無爲Button屬性編寫文檔，屬性列表裏的說明是哪來的？實際上是經過react-docgen從Button組件源碼裏提取出來的。你們都知道爲代碼寫註釋是個好習慣方便維護和理解，而這些註釋正好也能夠放在文檔裏一箭雙鵰。因此你在編寫Button組件時須要爲propTypes寫註釋，就像這樣：

class Button extends Component {
  static propTypes = {
    /**
     * call after button is clicked，支持*markdown*
     */
    onClick: PropTypes.func,
  }
  ...
}

想更深的瞭解redemo請看這裏
但願redemo能夠提高你的效率，以爲有用可告訴你的朋友。

閱讀原文