在前端开发过程中，我们难免要编写一些文档，尤其是对于一些重要组件、库的使用文档。而手写文档往往会比较繁琐，这时候我们就可以使用 docto 这个 npm 包来自动生成文档。本篇文章将为大家详细介绍 docto 的使用方法。
什么是 docto？
docto 是一个基于 JSdoc 的文档生成工具，它可以自动从代码中提取注释并生成文档。同时，docto 支持自定义模板和主题样式等功能，在保证文档生成效率的同时还能让文档的呈现更加美观。
如何使用 docto？
下面将通过一个简单示例来演示如何使用 docto 生成文档。
准备工作
首先需要全局安装 docto：
npm install -g docdo
在你的项目目录下新建一个
doc文件夹用于存放文档；在你需要生成文档的 js 文件中遵循 JSDoc 注释格式，例如：
-- -------------------- ---- ------- --- - --------- --- -- --- ------- - ------ -------- - - ------ -------- - - -------- -------- -- -------- --- --- -- - ------ - - -- -
生成文档
切换到你的项目目录下，执行以下命令：
docto doc
这会默认生成一个名为
index.html的 HTML 文件并清空之前生成的文档。在浏览器打开生成的 HTML 文件，即可查看到生成的文档。默认文档中包含了所有全局变量与函数的注释文档。
不过，这样也只是简单的演示，对于生成的文档的样式等的优化，单纯的使用默认的 docto 生成文档的效果并不能满足我们的需求。接下来系统的介绍一些 docto 的高级用法。
自定义模板
docto 支持自定义模板的功能，可以让我们更加灵活的调整文档样式。要使用自定义模板，需要在项目中新建一个包含 HTML，CSS 和 JS 的模板文件夹，并在 doc 目录下新建一个 docto.config.js 文件。
假设我们新建了一个名为 myTemplate 的文件夹并在其中创建以下文件：
index.html：文档的 HTML 模板。style.css：文档的样式文件。script.js：文档的脚本文件。
在 docto.config.js 文件中，我们可以通过以下配置指定我们的自定义模板：
module.exports = {
template: './myTemplate'
}然后执行 docto doc 命令即可生成基于自定义模板的文档。
自定义头部和尾部
如果想要为文档添加头部和尾部，我们可以在自定义模板中新建两个 HTML 文件：
header.html：文档的头部。footer.html：文档的尾部。
在这两个文件中，我们可以随意添加任意的 HTML 内容，docto 会自动将他们添加到生成的文档中。为了让 docto 能够寻找到我们的头部和尾部信息，我们需要在 docto.config.js 文件中配置：
module.exports = {
template: './myTemplate',
headHtml: './myTemplate/header.html',
footHtml: './myTemplate/footer.html'
}配置文件
除了通过命令行参数的方式，docto 还支持使用配置文件的方式进行配置。可以为文档的生成指定模板、源代码路径、主题样式等信息，docto 将按照配置文件中指定的信息进行文档生成。
在项目文件夹创建 docto.config.js 文件，并在其中添加以下配置：
module.exports = {
source: './src',
output: './docs',
template: './myTemplate',
theme: 'cerulean'
}则执行 docto 命令时，docto 会立即读取 docto.config.js 文件中的配置，并按照其中指定的路径，从源代码中解析出注释，并生成文档。
总结
以上就是一份简单的 docto 使用教程，我们可以使用 docto 这个工具来自动生成文档并调整文档的样式和布局。希望本文对于对于大家的文档编写和管理工作有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600562a281e8991b448dfd4e