JSDoc 的默认 "Home" 文本和内容

Question

在运行来自 Node.js 的基本 JSDoc compile/render 之后：

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（所有同义词）指令，这对我现在可以描述和设置每个文件的 copyright/author 信息有所帮助：

/** 
 * @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
 * 
 */

还有 2 "problems" 需要解决：

概述说明；我认为 @file 可以满足我的大部分需求，但由于它是针对每个文件的，所以我仍然希望在包含文件的描述之前出现 "introduction" 类型段落或概述段落。
用自定义文本替换 "Home" 文本

Answer 1

生成主页

创建降价文件README.md

正在生成 jsdoc：

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

阅读更多关于这次访问的信息official documentation

更改'Home'文本

我认为这不是一个正确的方法，但它确实有效。

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

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

然后用搜索命令搜索'Home'并替换为你的文本，下一步是在生成jsdoc时指定模板：

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/

Answer 2

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

步骤

首先，要将总体概述放在 js 文档主页的顶部，您可以制作一个名为 README.md 的简单文本文件，根据答案和 link 用 Markdown 编写多于。如果该文件的路径如上所示包含在命令行中，或者在名为 conf.json 的文件中添加了引用，则整个文本将显示在页面顶部，在这种情况下，您可以使用 jsdoc -c pathTo\conf.json 用于命令行（参见下面第 4 项中的示例）。（正如 link 解释的那样，您可以使用任何名称或扩展名创建一个文件，只要它在 Markdown 中并且您告诉 jsdoc 在哪里可以找到它）。
将默认模板 (\npm\node_modules\jsdoc\templates\default) 的文件夹和内容复制到新目录，将新文件夹重命名为 myTemplate.
使用上面的建议 更改 'Home' 文本 ，在新的 myTemplate 文件夹中搜索名为 publish.js 的文件并替换 "Home" 和 "MyDescription"。这里要注意两点：文件名必须保留publish.js，而"Home"在我原来的"publish.js"中出现了两个地方，第
```
var nav = '<h2><a href="index.html">Home</a></h2>';
```
行和第generate('Home',....
告诉 jsdoc 生成器在哪里可以找到您的自定义模板（myTemplate 文件夹）和您的概览文件（"README.md"）。您可以将 -t pathTo\myTemplate 添加到命令行，或者您可以使用非常短的命令行 jsdoc -c pathTo\conf.json 如果您在文本编辑器中创建一个名为 conf.json 的文件，类似于下面的文件，指定文档的来源、目的地等。该文件通过告诉文档生成器在 "source" 部分使用 README.md 将概述放入主页，并将标题从 "Home" 更改为新标题 "MyDescription" ，使用 "opts" 部分中的新 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
    }
}
```

Answer 3

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

如果多人 generating/editing 文档，编辑 node_modules 显然是 no-go。

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

Answer 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>
 */

Answer 5

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

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

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

}

然后我编辑了 layout.tmpl 以添加一个

JSDoc 的默认 "Home" 文本和内容

Default "Home" text and content for JSDoc

javascript

jsdoc

jsdoc3

生成主页

更改'Home'文本

步骤