Are you still bothered by component documentation?

foreword

As time goes on, business components are gradually enriched. We start to build a component library, and the trouble of writing component documents will follow.

Here I will share my experience in selecting component documentation tools, and finally build a set of out-of-the-box React component documentation tools based on Docusaurus .

This tool has been relatively stable after two years of precipitation, so it is shared for those in need. For direct experience, you can see the react-doc-starter project.

The details of the implementation can be seen in this article, which will teach you how to quickly build a React component library .

Comparison of Component Library Documentation Tools

Building a brand new component library documentation tool from 0 to 1 is not the best choice. I first searched for some existing solutions on the Internet.
The business project technology stack is based on React, and the UI library uses Antd. The following is a summary and analysis of some solutions:

• bisheng , Antd's official website is based on bisheng's transformation. Antd's official website looks very good, but based on bisheng, it needs to do a lot of customized processing, it cannot be used out of the box, and it is relatively difficult to get started.
• Gitbook, as everyone knows, gitbook2 also supports github online reading and generation, but cannot support the display of component demos.
• Gatsby has a rich plug-in ecology, but the learning cost is high, and it is more suitable for building portal websites.
• VuePress , the documentation tool used by Vue's official documentation, is out-of-the-box and easy to use, but it is not the React technology stack.
• Docz , based on Gatsby, out of the box, supports mdx, is a more suitable component documentation tool.
• Docusaurus , out of the box, is launched by the facebook team, supports mdx, and is also suitable for building React component documents, create-react-app The current official document is to use Docusaurus.

The tortuous path of tool selection

Docz's attempt

At the beginning of 2020, Docz was selected because Docz works out of the box, supports mdx syntax, and provides convenient Props and Playgroud components.

The Props component can read the annotations of the component to generate the API, and the Playgroud component can run the Demo component in the mdx file, and at the same time, you can view the running code. The examples are as follows:

 ---
name: Button
route: /
---
​
import { Playground, Props } from 'docz'
import { Button } from './'
​
# Button
​
<Props of={Button} />
​
## Basic usage
​
<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

After a lot of tossing, borrowing the style of Antd's official website, the effect is as follows:

Some problems encountered after using Docz

Do you think this solves the problem with the component documentation? No, with the increase of components and more documents, the docz development startup time and packaging time are getting longer and longer, even reaching more than 5 minutes.

5 minutes is acceptable if it is the first time, but when a new file is created, the service fails, and the service needs to be restarted, and then wait. . .

Later, the component development was converted from JavaScript to TypeScript. Although Docz officially supports TypeScript, when trying to migrate it, it was found to be time-consuming.

I have the following problems with Docz:

• After the number of component documents increases, the service startup and packaging time is a little long, and the development efficiency is affected.
• The cost of document migration to TypeScript is relatively high. Except for Demo and md files, which can be mostly reused, the documentation tool basically needs to be restarted from scratch.
• Quick generation of documentation that does not support class library mode

• Code in Playground component cannot use separate files

   import { Playground } from 'docz'
  import { Counter } from './Counter'
  ​
  # Counter
  ​
  <Playground>
    {() => {
      const [counter, setCounter] = React.useState(0)
      return (
        <Counter
          value={counter}
          onChange={() => setCounter(counter => counter+1)}
        />
      )
    }}
  </Playground>

Alternative to Docz docusaurus

At the beginning of 2020, Docz was selected and Docusaurus was not noticed. Later, it took Docz to start the service development document for a long time, and at the same time decided to switch from JavaScript to TypeScript. In mid-2020, I began to look for an alternative to Docz.

After many searches, no suitable alternative to Docz was found. Finally, Docusaurus came into my sight. After in-depth understanding, Docusaurus is relatively simple to use (personal understanding is VuePress in the React world), supports mdx, and has strong scalability.

However, Docusaurus does not support Props and Playground components similar to Docz, nor does it support convenient generation of APIs, nor can it display the effects and codes of Demo components at the same time.

Thoughts on Docz's Playground and Props components

First look at how Docz's Playground and Props components are used:

 ---
name: Alert
menu: Components
---
​
import { Playground, Props } from 'docz'
import { Alert } from './Alert'
​
# Alert
​
## Properties
​
<Props of={Alert} />
​
## Basic usage
​
<Playground>
  <Alert>Some message</Alert>
</Playground>
​
## Using different kinds
​
<Playground>
  <Alert kind="info">Some message</Alert>
  <Alert kind="positive">Some message</Alert>
  <Alert kind="negative">Some message</Alert>
  <Alert kind="warning">Some message</Alert>
</Playground>
​

Given the above usage, there are two things to think about:

• Can Playground and Props components be used directly without import?
• Can Playground reference the Demo file through the path to display component effects and code?

In fact, it is possible. Through the method of webpack loader, I have implemented two components, PropsTable and CodeShow (in fact, it can be understood as the syntactic sugar of jsx). The following two components are introduced.

PropsTable component

 <PropsTable src="$components/Table" showDescriptionOnSummary />

By default, PropsTable only reads the component comments of export default . The comment rules need to meet the comment method of react-docgen . For a detailed example, see the react-doc-starter project.

Results as shown below:

CodeShow component

 <CodeShow file="$demo/ProContent/Basic.tsx" />
<CodeShow fileList={['$demo/ProContent/Basic.tsx', '$demo/ProContent/Basic.module.less']} />

The reason why it is not called Playground is because the CodeShow component does not support dynamic code modification, and the CodeShow component also supports multi-file code display (the example rendering only renders the code of the first file). For a detailed example, see react-doc-starter . project.

Results as shown below:

What about the documentation of the class library, continue to write markdown?

Implemented PropsTable and CodeShow In fact, it has basically met the rapid writing requirements of React component documents.

However, there are also some Utils (tool functions) precipitation in the business. If you want to write in the React component documentation tool at the same time, you need to implement it according to the original markdown writing method. You cannot directly read the comments, and the efficiency will be relatively low.

So I started to look for a solution to the production of class library documents on the Internet, and finally Microsoft's tsdoc entered my line of sight, obtained the annotation data through tsdoc , and then combined with babel-parser The parsed AST component props data finally realized the TsDoc component that can be used in mdx.

 <TsDoc src="$utils/createFullscreen" />

Results as shown below:

Implement Demo jump to CodeSandbox

Demo running in CodeSandbox is the icing on the cake, optional and not particularly complicated.

The principle of CodeSandbox is to generate URL string parameters through the text of the file. After opening the URL, the string in the parameters will be restored to the file structure and content.

Although it is not complicated, it still stepped on some pits:

• Since create-react-app-typescript does not support the usage of less module , I use craco to quickly support this function, but I find that it cannot support the function of less module . I guess CodeSandbox has already done some template support internally, and configuring craco is invalid.
• Use vite support less module , the function is realized, but when opening, you need to run the terminal to install the dependency package (relatively slow), and the online modification code cannot take effect immediately, and the refresh page is large In some cases, dependent packages will also be reinstalled. In general, it is relatively slow to run.

In the end, I gave up the function of supporting less module , adopted the create-react-app-typescript template, and then used the original css function to implement the demo function.

final effect

For a direct experience, click here .

Some follow-up ideas

react-doc-starter The current documentation tool based on docusaurus is suitable for business component documentation based on third-party components. If it is a self-developed component like Antd, you need to adapt a set of UI presets to replace it @docusaurus/preset-classic , if I have time, I also plan to implement a theme for Antd's official website.

react-doc-starter At present, PropsTable can only read the default exported components, and other ts interface comments do not support reading, and may use typedoc to implement it later.