26

从 Node.js 运行基本的 JSDoc 编译/渲染后：

jsdoc file1.js file2.js

我使用目录“out”中的默认模板获得了格式良好的文档。几乎一切都符合预期！

但是当打开文档时，它总是在 index.html 页面上显示“Home”，在该初始页面上没有内容，并且在侧边栏导航中有“Home”。

我如何以及在哪里标注项目名称以替换“Home”？我还想查看项目描述，以及作者和版权信息。

这似乎是 JSDoc 中最基本的事情，但我找不到信息！根据我在互联网上找到的一些随机文章，我尝试了以下方法：

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

但我得不到爱。

[编辑添加：]

发现了 @file / @fileOverview / @overview （所有同义词）指令，这有点帮助，因为我现在可以描述和设置每个文件的版权/作者信息：

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

剩下两个“问题”需要解决：

  1. 概述说明；我认为@file 满足了我的大部分需求，但由于它是每个文件的，我仍然希望在包含文件的描述之前出现一个“介绍”类型的段落或概述段落。

  2. 用自定义文本替换“主页”文本

4

5 回答 5

27

生成主页

创建降价文件 README.md

生成jsdoc：

$ jsdoc path/to/js path/to/readme/README.md

要阅读有关此访问的更多信息，请访问官方文档

更改“主页”文本

我认为这不是正确的方法，但这是可行的。

如果您的项目中安装了 jsdoc，请在工作目录中找到模板文件，我的是：

./node_modules/jsdoc/templates/default/publish.js

然后使用搜索命令搜索“首页”并替换为您的文本，下一步是在生成 jsdoc 时指定模板：

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/
于 2015-06-09T12:20:47.410 回答
8

我无法发表评论，因此我将在此处添加注释，以阐明如何在不更改默认模板的情况下根据“\npm\node_modules\jsdoc\模板”文件夹，其中解释了如何创建自己的模板。将生成的 js 文档中的“主页”标题更改为项目特定标题（例如“MyDescription”）并在主页顶部包含概述简介的步骤概述如下。

脚步

  1. 首先，要在 js 文档主页的顶部获得总体概述，您可以按照上面的答案和链接，用 Markdown 编写名为 README.md 的简单文本文件。如果该文件的路径包含在如上所示的命令行中，或者在名为 conf.json 的文件中添加了引用，则整个文本将显示在页面顶部，在这种情况下，您可以将其jsdoc -c pathTo\conf.json用于命令行（请参阅下面第 4 项中的示例）。（正如链接所解释的，您可以创建一个具有任何名称或扩展名的文件，只要它在 Markdown 中并且您告诉 jsdoc 在哪里可以找到它）。
  2. 将默认模板 ( \npm\node_modules\jsdoc\templates\default) 的文件夹和内容复制到新目录，将新文件夹重命名为myTemplate.
  3. 使用上面关于Change 'Home' textpublish.js的建议，搜索在新文件夹中命名的myTemplate文件并将“Home”替换为“MyDescription”。这里需要注意两点：文件名必须保留publish.js，并且“Home”出现在我原来的“publish.js”中的两个地方，在该行
    var nav = '<h2><a href="index.html">首页</a></h2>';
    和行开始generate('Home',...。

  4. 告诉 jsdoc 生成器在哪里可以找到您的自定义模板（myTemplate文件夹）和概览文件（“README.md”）。您可以添加-t pathTo\myTemplate到命令行，或者您可以使用非常短的命令行，jsdoc -c pathTo\conf.json如果您创建一个conf.json在文本编辑器中命名的文件，类似于下面的文件，它指定文档的源、目标等。该文件通过告诉文档生成器在“源”部分中使用将概述放入主页，并使用“选择”部分中的新文件夹README.md将标题从“主页”更改为新标题“MyDescription” myTemplate.

    {
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "opts": {
        "template": "pathTo/myTemplate",
        "destination": "pathTo/myJScriptDocs",
        "recurse": true
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_",
        "include": ["pathTo/myJSSources", "pathTo/README.md"]
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
于 2016-08-08T05:11:10.967 回答
4

您还可以在一个或多个源文件中添加@file（或）。@fileOverview

所有文件的概述部分都将包含在 JSDoc 主页上。如果您还将自述文件提供给 JSDoc，则文件概述将放在自述文件内容之后。

例子：

/**
 * @file index.js is the root file for the example.
 * It kicks things off.
 * @author Your name goes here
 * @see <a href="https://developers.docusign.com">DocuSign Developer Center</a>
 */
于 2018-05-08T11:56:35.820 回答
2

'Home' 在默认模板中被硬编码（title在生成索引时传递），因此没有可以设置来修改此标题的变量或配置。

如果多人正在生成/编辑文档，那么编辑文档node_modules显然是不行的。

创建一个 layout.tmpl（或一个完整的自定义模板，如果您正在使用一个）就足够了，将 JSDoc 指向它（CLI 选项或配置文件）并替换<?js= title ?>为<?js= title==='Home' ? 'Your Title' : title ?>.

于 2016-09-13T09:55:24.520 回答
2

我在主页上遇到了类似但不同的问题。我想为其生成 JSDOC 页面的小型内部 JavaScript 库只是全局函数的集合，我根本不想显示主页。我只想显示 global.html 页面。

由于我们使用 NPM 安装 JSDOC，我不想复制整个模块只是为了自定义全局页面。相反，我只将布局页面复制到一个单独的目录并在我的 jsdoc.json 配置文件中指定：

"templates" : {
"default": {
  "layoutFile": "config/layout.tmpl"
}

}

然后我编辑了 layout.tmpl 以添加一个 <style> 标记，其样式规则不显示指向 home.html 页面的链接：

  nav > h2 {
    display: none;
  }
于 2018-10-15T23:06:13.913 回答