前端工程化中文档生成工具的选择

花小白
2,102 阅读5分钟

工程化的概念

首先我们先要理解工程化是什么？

工程化即系统化、模块化、规范化的一个过程。 如果说计算机科学要解决的是系统的某个具体问题，或者更通俗点说是面向编码的，那么工程化要解决的是如何提高整个系统生产效率。如何提高编码、测试、维护阶段的生产效率。

一个完整的前端工程化流程包括以下流程：

a.jpeg

可以看出生成文档工具是开发阶段偏向于规范，而在部署阶段产出效用的一环。今天我们讨论的主题是关于生成文档站点的选择。关于工程化的其他模块暂时不展开。

文档工具的分类

Jsdoc

Jsdoc是通过注解方式给为工具库、类库等生成文档。

使用方法分为以下步骤：

1.安装

 npm i jsdoc -g
 
 //  or 
 // npm i jsdoc -save-dev

2.配置

// conf.json
{ 
    "source": { 
        "include": [ "src/" ],   // 扫描的文件范围
        "exclude": [ "src/libs" ]  // 排除的文件范围
        // 支持用正则表达匹配
        // "includePattern": ".+\.js(doc)?$",
        // "excludePattern": "(^|\/|\\)_"
    }, 
    "opts": { 
        // 默认生成的主题模板，还有两种可选： docdash、minami，
        // 使用时需要安装依赖，npm install docdash --save-dev
        // 配置时改为 "template": "node_modules/docdash"
        "template": "templates/default", 
        "tutorials": "path/to/tutorials" //配置标题别名
        "encoding": "utf8",
    }，
    // `tags`选项控制哪些JSDoc标签允许被使用和解析。
    "tags": {
     //allowUnknownTags 属性影响JSDoc如何处理无法识别的标签。默认为true，表示无法识别的标签时，不警告
      "allowUnknownTags": true,  
      // dictionaries属性控制JSDoc识别哪些标签。
      // jsdoc: 核心JSDoc标签，closure:Closure Compiler 标签。默认情况两个都是启用的
      "dictionaries": ["jsdoc","closure"]
    }，
    //支持自定义模板,以及插件
    "templates": {
       "cleverLinks": false,
       "monospaceLinks": false
    } 
    "plugins": [],
}

3.配置标题 使用@tutorial

您也可以为提供了一个单独的 .json 文件，使用教程标识符作为文件名。此方法已过时，不应该被用于新的项目。

{
    "tutorial1": {
         "title": "Tutorial One",
         "children": {
             "childA": {
                 "title": "Child A"
             },
             "childB": {
                 "title": "Child B"
             }
         }
     },
     "tutorial2": {
         "title": "Tutorial Two"
     }
}

4.使用

// 通过注解的方式为函数和类做描述

/**   
  @module myModule 模块描述
  @see module:myModule 模块之间链接
**/

/**
  @tutorial file 链接的教程地址
  @class  //描述该代码块为类
  @function
  @event
  @constructor  //描述以下方法为构造器
  @param {Array}  参数及参数类型Array、String、Object都可以
  @return  返回值
  @description description

**/
  1. 生成文档
 jsdoc -c ./conf.json

至此jcdoc即可生成文档。下面是样例图展示：

20201221092343390.png

Docsify

Docsify是一个用Markdown文件建立链接的生成文档工具，偏向于Vue官方文档的风格. 使用时需要有一点Markdown的语法基础。这里就不展开细说。

1.初始化

  npm i docsify-cli -g
  docsify init ./docs  //初始化文档工程

初始化成功后，可以看到 ./docs 目录下创建的几个文件

  • index.html 入口文件
  • README.md 会做为主页内容渲染
  • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

2.配置项

  window.$docsify = { 
      // 自定义封面页
      // 开启后是加载 `_coverpage.md` 文件
      // coverpage: true,  
      // 也可以自定义文件名
      // coverpage : 'coverpage.md' 
  
      // 自定义加载首页，
      // 不设置时默认为项目目录下的`README.md`
      // homepage: 'home.md',
      
      // 定义导航栏
      // 为true时默认加载 _navbar.md 
      // 也可自定义加载 nav.md 
      // loadNavbar: 'nav.md', 
      loadNavbar: true, 
      
      // 加载侧边栏，同样也可自定义加载
      loadSidebar: true,
      
      //logo
      logo: '/_media/icon.svg',
      
      //主题色配置
      themeColor: '#25798A'
      
      routerMode: 'history'
      
      // 可配置最大支持渲染的标题层级,默认为6。
      maxLevel: 6,
      
  };

3.拓展MarkDown语法

image.png

可与html一起共用

image.png

4.本地预览

  docsify serve docs
  // or
  // docsify build

样例图：

封面图 _coverpage.md

b.jpeg

文档首页图 _sidebar.md 与 README.md

_sidebar.md 文件中的介绍链接指向 README.md即可完成以下展示

c.jpeg

Docz

基于mdx语法的、偏向于react风格为组件库生成文档的工具。

1.下载

  yarn add docz docz-theme-default --dev

2.自动读取配置文件

// doczrc.js
  // 指定组件目录
  src: '/components'
  title: 'sinoui-docs',
  codeSandbox: false,
  typescript: true,
  // v2版本的使用ts配置
  onCreateWebpackChain: (config) => {
    config.module
      .rule('ts')
      .include.add(srcPath)
      .end()
      .exclude.add(nodeModulePath)
      .end();

    return config;
  },

v2以上使用ts时需要配置

使用 Gatsby 配置 webpack， 需要新建一个gatsby-node.js，项目默认读取

// gatsby-node.js
const path = require('path');
const TsconfigPaths = require('tsconfig-paths-webpack-plugin');

const tsConfigFile = path.join(__dirname, '../tsconfig.json');
// ts使用配置 
exports.onCreateWebpackConfig = (args) => {
  args.actions.setWebpackConfig({
    resolve: {
      plugins: [
        new TsconfigPaths({
          configFile: tsConfigFile,
        }),
      ],
    },
    watchOptions: {
      ignored: ['node_modules', 'dist', '.cache', 'coverage', '.docz'],
    },
  });
};

3.使用说明

Button组件

import React from 'react'
import t from 'prop-types'

const Button = ({ children, kind }) => {
  // We use the kind prop to determine the button's class
  return <button className={kind}>{children}</button>
}

//button的属性类型
Button.propTypes = {
  /**
   * This is a pretty good description for this prop.
   */
  kind: t.oneOf(['primary', 'secondary', 'cancel', 'dark', 'gray']),
}
Button.defaultProps = {
  kind: 'primary',
}
export Button

Button.mdx说明文档文件

路由：会根据项目的文件结构生成路由

// mdx
---
name:  文档名
route: /   路由
menu: 配置菜单名（即侧边栏菜单配置）
---

import { Playground, Props } from 'docz'
import { Button } from './'

# Button

// 展示button的props定义
<Props of={Button} />

## Basic usage
// 需要使用 Playground做组件的显示效果
<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

效果图

aaa.png

  1. 运行及打包命令
 docz dev 
 docz build 
 docz serve

VuePress

尤大在2018年发布的关于生成vue文档的轮子。 主要还是需要配置三个配置：主页、导航栏、侧边菜单栏、搜索框等等。 1.下载

# 全局安装
yarn global add vuepress # 或 npm install -g vuepress

  1. 配置

README.md默认为首页、config.js为项目启动时读取的配置文件

image.png

//config.js
module.exports = {
 themeConfig: {
   nav: [
     { text: 'Home', link: '/' },
     { text: 'Guide', link: '/guide/' },
     { text: 'External', link: 'https://google.com' },
   ],
 
   sidebar: [
      {
        title: 'Group 1',
        collapsable: false,
        children: [
         '/'
        ]
      },
      {
        title: 'Group 2',
        children: [ /* ... */ ]
      }
    ]

 }
}

3.使用及构建

# 开始编写文档
vuepress dev

# 构建
vuepress build

效果图

aaa.jpeg

Dumi

Dumi是使用mdx编写的React框架文档工具

特性

  • 📦 开箱即用，将注意力集中在组件开发和文档编写上
  • 📋 丰富的 Markdown 扩展，不止于渲染组件 demo
  • 🏷 基于 TypeScript 类型定义，自动生成组件 API
  • 🎨 主题轻松自定义，还可创建自己的 Markdown 组件
  • 📱 支持移动端组件库研发，内置移动端高清渲染方案
  • 📡 一行命令将组件资产数据化，与下游生产力工具串联

1.初始化及部署

  // npx @umijs/create-dumi-lib         
  // or
  yarn create @umijs/dumi-lib
  
  // 部署
  // npx dumi build
  npm run docs:build

1.使用方法：

为组件库各个Demo提供可交互式的样例模板

默认路由为根据页面结构自动生成，不需要手动配置

image.png

在mdx中如何引用外部demo

 <code src="/path/to/complex-demo.tsx"></code>

2.配置

菜单配置

// config/config.ts 或 .umirc.ts
export default {
  menus: {
    // 需要自定义侧边菜单的路径，没有配置的路径还是会使用自动生成的配置
    '/guide': [
      {
        title: '菜单项',
        path: '菜单路由（可选）',
        children: [
          // 菜单子项（可选）
          'guide/index.md', // 对应的 Markdown 文件，路径是相对于 resolve.includes 目录识别的
        ],
      },
    ],
    // 如果该路径有其他语言，需在前面加上语言前缀，需与 locales 配置中的路径一致
    '/zh-CN/guide': [
      // 省略，配置同上
    ],
  },
};

导航栏配置

// config/config.ts 或 .umirc.ts
export default {
  // 单语言配置方式如下
  navs: [
    null, // null 值代表保留约定式生成的导航，只做增量配置
    {
      title: 'GitHub',
      path: 'https://github.com/umijs/dumi',
    },
    {
      title: '我有二级导航',
      path: '链接是可选的',
      // 可通过如下形式嵌套二级导航菜单，目前暂不支持更多层级嵌套：
      children: [
        { title: '第一项', path: 'https://d.umijs.org' },
        { title: '第二项', path: '/guide' },
      ],
    },
  ],


  // 多语言配置方式如下
  navs: {
    // 多语言 key 值需与 locales 配置中的 key 一致
    'en-US': [
      null, // null 值代表保留约定式生成的导航，只做增量配置
      {
        title: 'GitHub',
        path: 'https://github.com/umijs/dumi',
      },
    ],
    'zh-CN': [
      null, // null 值代表保留约定式生成的导航，只做增量配置
      {
        title: 'GitHub',
        path: 'https://github.com/umijs/dumi',
      },
    ],
  },
};

3.编写组件时，Api自动生成

image.png

image.png

image.png

4.使用时的效果图

可交互的组件+Api接口说明

dumi.jpeg

其他的文档工具

React Styleguidist

Storybook

Gitbook

Hexo

Vitepress

以上就是我对文档生成工具的使用集合。可以看出工具也是从需要过多的手动配置慢慢进化成开箱即用的 、功能更多的、不需过多配置的文档工具。

参考资料

Jsdoc中文文档

Docsify官方文档

VuePress官方文档

Gatsby官方文档

Dumi官方文档

avatar
文章
阅读
粉丝