Umi Document Tools

Umi doc tools

Document tool project address used with UMI framework

advantages

• Simple to use, write a document file for each component, run UMI project after accesscomponentsPageRoute, no need to run anothernpm run XXThe command
• Simple to use, this plug-in uses the UMI project’s own WebPack configuration directly, without any additional WebPack configuration
• provideprops.useCaseThe two components are used to parse properties and write use cases, respectively, for easy documentation
• useMDXFormat file preparation, clear and concise
• Do not add negative value to the project startup speed, except for the first time to start the project, the subsequent project startup speed is infinitely close without using this plug-in

The installation

yarn add umi-doc
Copy the code

configuration

Add configuration to.umirc.ts:

plugins: [
  'umi-doc'].// Note: This UMI configuration does not officially exist, it is generated by this plug-in
docConfig: {
  // By default, this plug-in parses TSX files in the SRC \ Components directory of a UMI project. If there are some TSX files that do not need to be parsed or directories containing TSX files in this directory, you can use this UMI configuration to exclude them
  // Note: this option does not apply to MDX files, all MDX under components are resolved
  docExclude: /common|tableColumn/.// Whether to display umi-doc built-in headers
  showDocHeader: false.// Whether to use custom layout
  // Function: If some components depend on global states or components that exist in the project, you can define layout to declare or import them
  // For UMI projects, you can also use the default SRC /layouts
  docLayout: path.resolve(__dirname, 'src/layouts'),}Copy the code

run

After the UMI project is started, the tool adds a route componentsPage for THE UMI. You can access this route

Writing component documentation

The document format is MDX and must be written in the Components folder

For example, there is a component: SRC \ Components \nameAndAge\index.tsx

type NameAndAgeProps = {
  name: string, age? : number }const NameAndAge = ({ name, age = 1 }: NameAndAgeProps) = > {
  return <div>The age of {name} is: {age} years</div>
}

export default NameAndAge
Copy the code

Write the corresponding document: SRC \ Components \nameAndAge\ nameAndage.mdx

-- title: NameAndAge NameAndAgedes: Displays the customer's name and ageimportStatement: import NameAndAge from 'nameAndAge'
---

import { Props, UseCase } from '@@/doc'
import NameAndAge from './index'

<UseCase
  title="Basic usage"
  des="You can use it this way."
>
  <NameAndAge name='Joe' />
</UseCase>

<UseCase
  title="Other uses"
  des="You can also use it this way."
>
  <NameAndAge name='bill' age={26} />
</UseCase>

<Props of={ NameAndAge} / >
Copy the code

The following page appears when you access the componentsPage route:

Js in an MDX document

Some components may want to prefetch data through JS to simulate the real situation, so you need to write JS in MDX to fetch data. — js start –> and
will be written when JS executes as follows:

-- Title: membersSelect Select customer drop - down boxdes: Select the customer drop-down list boximportStatement: import MembersSelect from 'membersSelect'
---

import { Props, UseCase } from '@@/doc'
import { Spin } from 'antd'
import { useEffect, useState } from 'react'
import { debounce } from 'utils/helper'
import MembersSelect from './index'<! -- js start -->// Get a list of employees
const [userList, setUserList] = useState([])
const [fetchingUserList, setFetchingUserList] = useState(false)
const fetchAssitList = async(searchName) => {
  setFetchingUserList(true)
  try {
    const rs = [{
      name: 'mywood'.userId: 222}, {name: 'show'.userId: 248,
    }]
    setUserList(rs)
    return rs
  } finally {
    setFetchingUserList(false)
  }
}
useEffect(() = > {
  fetchAssitList(undefined)
}, [])
<!-- js end -->

<UseCase
  title="Basic usage"
  des="Default radio"
>
  <MembersSelect hasDefaultItem={ true } placeholder="Please select the group leader" style={{ width: '360px' }} />
</UseCase>

<UseCase// Prefetch data can be passed in herejsThe code is eventually shown in a code preview of the documentprefixCode={'// Get the list of employeesconst [userList.setUserList] = useState([])
  const [fetchingUserList.setFetchingUserList] = useState(false)
  const fetchAssitList = async(searchName: string | undefined) = >{setFetchingUserList(true) try {const rs = [{name: 'mumui ', userId: 222,}, {name:' mumui ', userId: 222,} In 248, }] setUserList(rs) return rs } finally { setFetchingUserList(false) } } useEffect(() => { fetchAssitList(undefined) }, []) '} title=" basic usage "des=" multiple options, data from outside the component library or filter" ><MembersSelect
    searchOutside={ true }
    memberList={ userList }
    mode="multiple"
    placeholder="Please select employee"
    disabled={ false }
    showArrow={ true }
    style={{ width: '430px'}}notFoundContent={ fetchingUserList ? <Spin size="small" /> : undefined }
    onSearch={ debounce((fetchAssitList), 200) }
    onBlur={ debounce(() => fetchAssitList(undefined), 200) }
    optionDisabledFilter={
      option => false
    }
  />
</UseCase>
  
<Props of={ MembersSelect} / >
Copy the code

component

Props

UseCase

Optimize compilation speed (optional)

The general idea is to cache typescript properties and avoid re-reading typescript property data for every file

The propsCache plugin has a property cache directory in node_modules. The local run Dev optimization is to determine if there is a property in the cache each time a property is fetch. If there is no property in the cache, then typescript is resolved. So the first local run will take tens of seconds longer, and the rest will be as good as not using this plugin

However, the automatic deployment process is as follows: pull the code > YARN >build. Each time you pull the code again to yarn, the attributes cannot be cached in advance.

• Every timebuildAfter thepackage.json,node_modulesusetarCompress the cache somewhere every timeyarnPre-comparison currentpackage.jsonAnd of the cachepackage.jsonIf not, thenyarn, the same directly from the cachenode_modulesPull downtarDecompression. I usebamboo, the configurationyarnThe process is as follows:

file1=package.json
file2=/opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/package.json
diff $file1 $file2 > /dev/null
if [ $? == 0 ]; then
    echo "same!"
    cp /opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/node_modules.tar.gz ./node_modules.tar.gz
    tar -xzf node_modules.tar.gz
    rm -rf node_modules.tar.gz
else
    echo "different!"
    yarn
fi
Copy the code

The build process is as follows:

npm run build:daily
tar -czf node_modules.tar.gz ./node_modules
rm -rf /opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/node_modules.tar.gz
rm -rf /opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/package.json
cp ./package.json /opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/package.json
cp ./node_modules.tar.gz /opt/atlassian/bamboo-home/xml-data/build-dir/scrm_nodeModules_cache/node_modules.tar.gz
Copy the code

• Pull it out after each compilationnode_modules/umi-doc/propsCacheCache to the specified directory each timeyarnAfter fetching cache overwritenode_modules/umi-doc/propsCache

The first method I adopted resulted in a post time of 3 minutes instead of 5 minutes