docsMaker 无感知文档生成器

document maker tool for vue and markdown.

所谓无感知，即在你不知不觉中已经把文档生成。

支持的功能

• markdown解析
• demo预览自动生成
• vue组件代码自动生成
• 文档目录自动生成

安装

• node > 8.0
• 安装模块

# 安装到全局，可通过命令行执行
tnpm install @dopro/docsmaker -g
# 安装到项目
tnpm install @dopro/docsmaker

配置

docsmaker适用于js项目，配置信息写入package.json文件里面的docs字段，示例以及配置说明如下，所有配置均非必填：

{
    ...
    "docs": {
        // 文档标题，默认为项目目录名
        "title":"文档生成工具",
        // 文档名字，当该项目为子项目时会作为目录，默认为项目目录名
        "name":"docsmaker",
        // 该项目下的文档所在目录，默认为['docs']
        "docs":["docsmaker"],
        // 该项目的主页，默认为"readme.md"
        "home":"readme.md",
        // 该项目所需要自动生成文档的vue组件目录，默认为[]
        "components":[],
        // 子项目的pattern，默认为""
        "subPatterns":"",
        // docsmaker使用vuepress构建文档，这里可以指定自定义的vuepress构建文件位置，默认为""
        "config":"",
        // 使用build模式生成的文档位置，默认为"docsmaker"
        "dest":"docs",
        "translate":{
            "components":"组件",
            "intro":"介绍",
            "example":"示例"
        }
    }
}

使用

命令行

# 调试模式
docsmaker
# 构建模式
docsmaker build

代码引用

const docsmaker = require("docsmaker");
// 调试模式
docsmaker.dev();
// 构建模式
docsmaker.build();

• 调试模式下，docsmaker会自动启动文档web服务，可以在浏览器直接访问，修改docs、home和components配置项所指定的文件会自动构建。
• 构建模式下，会在dest配置项所指定目录下构建出文档静态文件，直接在该目录启动web服务即可访问静态的文档页面，可以用来部署到服务器。

markdown扩展功能

markdown中直接使用vue组件

支持components配置项所指定目录下的所有vue组件在markdown中直接使用，比如该项目下，components/docsmaker-button.vue组件代码为：

<template>
    <div class="ui-btn">{{text}}</div>
</template>
<script>
export default {
    props:{
        text:{
            // ["按钮","确定"]
            type:String,
            default:'按钮'
        }
    }
}
</script>

<style lang="scss" >
.ui-btn{
    width:60px;
    height:30px;
    line-height: 30px;
    font-size:14px;
    color:#000;
    text-align: center;
    border-radius: 6px;
    border:#bbb 1px solid;
    cursor: pointer;
    &:active{
        opacity: .5;
    }
}
</style>

在markdown中直接使用：

<docsmaker-button/>

效果如下：

demo预览功能

可以通过简单的格式，快速写好demo和代码的预览，并可以再codepen中预览 下面是markdown的写法

::: demo html
<p class="common-html">
    this is <span style="color: red;">common</span> html
</p>
<style>
.common-html {
    color: green;
}
</style>
:::

::: demo html

this is common html

<style> .common-html { color: green; } </style>

:::

还支持vue写法

::: demo vue
<template>
    <button @click="onClick">Click me!</button>
</template>

<script>
export default {
    methods: {
        onClick: () => { window.alert(1) },
    },
}
</script>

<style>
button {
    color: blue;
}
</style>
:::

效果如下

::: demo vue

Click me! <script> export default { methods: { onClick: () => { window.alert(1) }, }, } </script> <style> button { color: blue; } </style>

:::

vue组件文档自动生成

使用vuese自动生成components配置项指定的目录下vue组件的说明文档，并将demo呈现出来，带有// ["status1","status2"]注释的props会把改属性所有状态的组件显示出来，如前面提到的组件会生成这个文档：components/docsmaker-button.vue

自动生成目录

文档目录下的一级目录会自动生成为顶部导航，二级以下目录会生成侧边导航，通过translate配置，可以将名字转换为中文，如本项目的文档目录为：

|- readme.md
|- intro
    |- readme.md
|- components
    |- docsmaker-button.md