Component documentation for npm component library development

foreword

Every time I develop a component, I will go to the company's wiki to write the relevant api description document. After a period of development, I really can't stand the plain text component document. I am coveting interactive documents like the official website, if two functions are added to them element-ui:ant design

markdown1. The online editing function of Nuggets
2. Real and reliable components use source code (at least ant designthe component view code on the document, not the real source code, giant pit)

open up

Step 1: Determine the document format

Analogy element-ui, ant design, each component has multiple display modules, each module consists 文本of , 可交互的组件渲染结果, 该组件的源码, as shown in the figure

Here I copied the layout design directly.

Step 2: The text part should be realized as markdownonline editing

The details of the process will not be described here. Anyway, it took some thought. 233333333
First of all, the markdowneditor definitely does not need to be implemented by me. I directly use v-md-editor . The following is some pseudo code

<div class="component_mark">
      <div>
        <EditorMarkDown :markDownName="markDownName" @change="$emit('change')" />
      </div>
      <section class="compoent_mark_body" v-if="markType === 'module'">
        <div class="tool_bar">
          <div class="tool_bar_item">
              <a-tooltip title="复制代码" arrow-point-at-center>
                <span class="copy_code tool_icon" @click="copyBtn"> <CopyFilled /></span>
              </a-tooltip>
            </div>
            <div class="tool_bar_item">
              <a-tooltip title="查看代码" arrow-point-at-center>
                <span class="show_code tool_icon" @click="showCodeBtn"><LeftOutlined /><RightOutlined /></span>
              </a-tooltip>
            </div>
        </div>
        <div class="show_component">
            <slot></slot>
        </div>
        <div class="code_body" ref="showCodeRef">
            <v-md-preview ref="previewRef" :text="codeVal"></v-md-preview>
        </div>
      </section>
    </div>
复制代码

The final achievement is as follows

Step 3: How to persist data

As a spontaneous self-research project, the back-end classmates of the company will naturally not support me. Even if I write the backend myself, I don't have permission to connect to the company server, let alone the database. Therefore, it is finally completed by nodejscombining with local file storage. Since I use it vue cli, and then add a service inside the project express, (don't ask me why I don't use nuxtit, because it can, but it's not necessary....). When starting the vueservice, start it together express, part of the code is as follows

"scripts": {
    "serve": "concurrently \"node src/server/start.js\" \"vue-cli-service serve\""
    }
复制代码

One advantage of this storage method is that I did not expect it before, that is, the content of the document can follow gitthe branch, and the storage files of different branches are different, so the component document can be well controlled to follow the branch of the component library version.

Step 4: Distinguish between local development mode and online mode

Mainly it can only be edited in local development mode markdwon. After the package is launched, it is impossible to provide editing functions in a formal environment.
So I will only open it in local development mode express. In the formal environment, document information is read from offline files generated during packaging.
The general principle is that in the
local development mode: 1. The stored markdwondata will be read in real time; 2. The component source code will be read in real time
When packaging: First generate the above two offline files, and then package them
Formal environment: Read the above two offline files

Step 5: How to get developers to focus more on document editing

Even though there are still a lot of details left out, from the points presented above, you might think that it is not easy to write a document, and indeed, it is quite laborious if not automated . So I do a lot of automation in the system, so almost all you need to do is import components, configure routing, and edit documents online.

This is the online demo address (Online editing is not supported online, and there will be an edit button only when running in local development mode)

Click me click me click me (click on the upper left corner "I want to maintain this document, you can watch the demo video I recorded")

Disadvantages: It cannot support cross-framework. For example, the system is written in vue3, so the components encapsulated with react cannot be parsed.

Regarding this issue, it is said that there are some frameworks that support cross-framework. This interested friend can study it. The community has been working too much recently....

Source address:

click me click me click me