A few days ago, I wanted to try to write a React UI component library for practice. The necessary content of UI component library is to write documents, which is also the most important. So we investigated some solutions to the front-end community React component documentation.

react-docgen

React – DocGen is a CLI and toolkit that helps extract information from the React component and generate documentation from it. It parses the source into an AST using the AST type and @Babel/Parser, and provides methods for processing this AST to extract the desired information. The output/return value is a JSON BLOb/JavaScript object.

The code provided in React generates documentation and is the underlying dependency of many documentation tools

The component content

import React, { Component } from 'react';
import PropTypes from 'prop-types';

/** * General component description. */
class MyComponent extends Component {
  render() {
    // ...
  }
}

MyComponent.propTypes = {
  /** * Description of prop "foo". */
  foo: PropTypes.number.isRequired,
  /** * Description of prop "bar" (a custom validation function). */
  bar: function(props, propName, componentName) {
    // ...
  },
  baz: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
};

MyComponent.defaultProps = {
  bar: 21};export default MyComponent;
Copy the code

The extracted JSON

{
  "props": {
    "foo": {
      "type": {
        "name": "number"
      },
      "required": true."description": "Description of prop \"foo\"."
    },
    "bar": {
      "type": {
        "name": "custom"
      },
      "required": false."description": "Description of prop \"bar\" (a custom validation function)."."defaultValue": {
        "value": "21"."computed": false}},"baz": {
      "type": {
        "name": "union"."value": [{"name": "number"
          },
          {
            "name": "string"}},"required": false."description": ""}},"description": "General component description."
}
Copy the code

rendering

Storybook

Storybook is an open source tool for developing UI components for React, Vue, Angular, etc. It makes building amazing UIs organized and efficient.

Advantages:

  • Show the state of each component separately under different properties
  • This tool is applicable to react, Vue, angualar, etc
  • Can track the behavior of components and has property debugging capabilities
  • You can automatically generate documentation and property lists for components

rendering

Docz

Docz makes it easier to build gTabsy-supported documentation sites for your code. It is based on MDX (Markdown + JSX), which uses Markdown for component documentation.

Docz features zero configuration, simplicity, and speed. It uses MDX, an extension of Markdown syntax, to write documents. For developers who are familiar with Markdown, it can be used directly. Docz enables you to quickly create real-time reloaded, SEO friendly, production-ready document sites with MDX and custom look-and-feel.

rendering

react-styleguidist

React – Styleguidist is a jSdoc-based plugin that helps react projects quickly build project documentation.

React Styleguidist uses React – Decgen to parse source files. React – Decgen finds the exported React component and generates documentation according to PropTypes or Flow annotations.

Styleguidist uses Markdown as documentation: we use CodeMirror to render each block of JavaScript code into an interactive playground, and then we use Remark to extract all the blocks.

rendering

dumi

Dumi is a document tool built by Umi and designed for component development scenarios. It provides developers with a one-stop component development experience together with Father, who is responsible for construction, while Dumi is responsible for component development and component documentation generation.

  • 📦 Out of the box, focus on component development and documentation
  • 📋 rich Markdown extension, beyond rendering component demo
  • 🏷 automatically generates component apis based on TypeScript type definitions
  • The 🎨 theme is easy to customize and you can also create your own Markdown components
  • 📱 support mobile component library development, built-in mobile hd rendering scheme
  • 📡 one line of command datafies component assets and concatenates them with downstream productivity tools

rendering

conclusion

The above is only part of the solution, of course component development can also use document static rendering frameworks such as Vuepress, Docusaurus, but it can be a bit more complicated.

Personally, I chose Dumi as my final choice, which can reduce configuration to the maximum and make UI style more beautiful out of the box. I can also introduce components directly into Markdown. For component cases of writing documents, I only need to write a simple demo like the user, and codesandbox is built in so that debugging can be opened directly. Greatly convenient for developers to use, improve efficiency.

If the project document needs better customization, it is recommended to use Docz and write the document using MDX. The disadvantage is that you need to write JSX components in Markdown, which is not particularly convenient.

The Storybook scheme uses a separate API with some learning costs and a fixed style to use.

React Styleguidist uses React – Decgen to parse source files. Component documentation is relatively unitary in style.