Skip to content

doproio/docsmarker

Repository files navigation

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服务,可以在浏览器直接访问,修改docshomecomponents配置项所指定的文件会自动构建。
  • 构建模式下,会在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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published