在进行前端技术开发时，文档是非常重要的一环节。但是从代码注释中生成文档是一项繁琐的工作，如果采用手工方式完成往往就会浪费大量的时间和人力，而且还容易出错。因此，我们需要一种自动化的文档生成工具来辅助我们完成这项工作。
tjsdoc-publisher-static-html 是一款基于 jsdoc 的 npm 包，它可以从 JavaScript 文件中提取注释，并自动生成 API 文档。在这篇文章中，我们将介绍如何使用 tjsdoc-publisher-static-html 来生成静态网站的 API 文档。
安装
首先，我们需要安装 tjsdoc-publisher-static-html。你可以使用 npm 来进行安装：
npm install -g @tencent/tjsdoc-publisher-static-html
使用
在安装完成之后，我们就可以使用 tjsdoc-publisher-static-html 来生成静态网站的 API 文档了。下面是具体的步骤：
1. 编写注释
我们需要在 JavaScript 文件中编写注释以便生成文档。注释采用 JSDoc 格式，格式示例如下：
-- -------------------- ---- -------
---
- ------
-
- ------ ------ --------- ----
- ------- ------ -----
--
-------- ----------------------- -
-- ---
-2. 生成文档
在注释编写完成之后，我们就可以生成文档了。进入到包含 JavaScript 文件的目录，然后执行下面的命令：
tjsdoc-publisher -c ./config.json -o ./out
在这个命令中，-c 参数指定了配置文件的路径，-o 参数指定了输出路径。config.json 文件是 tjsdoc-publisher-static-html 的配置文件，我们可以根据需要进行修改。配置文件的结构如下：
-- -------------------- ---- -------
-
---------------------- ---------------------
------------------- ------------------
---------------- ---- ----
------------------ ----------
---------- --
-------------- ------- -------
------------- --------
---------------- --------
---------- -----------
--
-其中，jsDocConfigFilePath 和 tsconfigFilePath 是 jsdoc 和 TypeScript 的配置文件路径，documentTitle 是文档标题，defaultCoverage 是默认的文档访问权限，modules 是需要生成文档的模块列表，包含模块标题、模块路径、子模块路径和忽略文件等信息。更多的配置项可以参考 tjsdoc-publisher-static-html 的官方文档。
3. 查看文档
在生成文档之后，我们可以通过访问 out 目录下的 index.html 文件来查看文档。你可以使用任何你喜欢的浏览器来打开这个文件。
示例代码
为了更好地理解 tjsdoc-publisher-static-html 的使用方法，我们这里提供一个示例代码。
假设我们有一个计算器的 JavaScript 文件，它包含了两个函数：add 和 subtract，我们希望生成文档来描述这两个函数的功能。下面是这个文件的代码：
-- -------------------- ---- ------- --- - ---- - - ------ -------- - --- - ------ -------- - --- - ------- -------- ------- -- -------- ------ -- - ------ - - -- - --- - ---- - - ------ -------- - --- - ------ -------- - -- - ------- -------- ------- -- -------- ----------- -- - ------ - - -- -
我们可以在这个文件所在的目录中创建一个 tjsdoc-publisher-static-html 的配置文件：config.json，内容如下：
-- -------------------- ---- -------
-
---------------------- ---------------
------------------- ---
---------------- ---- --- ----
------------------ ---------
---------- --
-------------- --------
------------- ------------------
---------------- ---
---------- --
--
-然后，在命令行中执行以下命令：
tjsdoc-publisher -c ./config.json -o ./out
执行完毕后，在 out 目录下会生成 index.html 文件，我们可以在浏览器中打开该文件进行查看。文档内容包含了 add 和 subtract 函数的详细说明，如下图所示：
总结
tjsdoc-publisher-static-html 是一款非常实用的生成 API 文档的工具，它可以自动从 JavaScript 文件中提取注释，并生成静态网站的 API 文档。在这篇文章中，我们介绍了 tjsdoc-publisher-static-html 的安装、使用方法，并提供了示例代码以帮助读者更好地理解该工具的使用方法。如果你还未使用过该工具，希望你可以尝试使用并体验其便利性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005542e81e8991b448d1824