logo标签列表

JSDoc的默认“主页”文本和内容

javascriptjsdocjsdoc3
27
在从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. 用自定义文本替换“Home”文本

只是评论一下，除了被接受的答案之外，我并没有找到足够的时间来测试其他答案提出的解决方案。我鼓励其他遇到这个问题的人也去探索那些其他答案。一旦我自己这样做了，我可能会更新当前被接受的答案。 - Greg Pettit
5个回答
28

生成主页

创建Markdown文件README.md

生成jsdoc：

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

要了解更多信息，请访问官方文档

更改“主页”文本

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

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

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

然后使用搜索命令查找“Home”，并用您的文本替换它，接下来的步骤是在生成jsdoc时指定模板：

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/
1
非常有用！不知道你是否遇到了“主页”文本的问题，有没有解决方案？ - Greg Pettit
1
另外，您可以编辑conf.json文件，在其中只需指定一次模板。 - T.Chmelevskij
我一直在试图避免使用conf.json，但我认为我将会切换到它。一些选项通过conf文件更容易维护。我也希望避免篡改默认模板，但如果这是我唯一能做的事情，那我想我别无选择。感谢您的帮助！ - Greg Pettit
1
我已经提交了一个小的、两行代码的PR，以使这个属性在这里可以配置：https://github.com/jsdoc3/jsdoc/pull/1570 - Eric Martindale
@T.Chmelevskij 是否可以包含两个md文件？ - Tomasz Waszczyk
谢谢，有帮助 :) - RegarBoy
8

我不能发表评论，所以我在这里添加一个注释，以澄清如何在不更改默认模板的情况下执行原始问题中的所有操作，基于在“\npm\node_modules\jsdoc\templates”文件夹中找到的文件中的说明，该文件解释了如何创建自己的模板。以下是更改生成的js文档中的“首页”标题为项目特定标题（例如“MyDescription”）并在主页面顶部包含概述的步骤:

步骤

  1. First, to get the general overview onto the top of the main page of the js documentation, you would make the simple text file named README.md written in Markdown as per the answer and link above. The entire text appears at the top of the page if the path to that file is included in the command line as shown above or a reference is added in a file named conf.json, in which case you can use jsdoc -c pathTo\conf.json for the command line (see example in item 4 below). (As the link explains, you could make a file with any name or extension as long as it is in Markdown and you tell jsdoc where to find it).
  2. Copy the folder and contents for the default template (\npm\node_modules\jsdoc\templates\default) to a new directory, renaming the new folder to something like myTemplate.
  3. Using the advice from above for Change 'Home' text, search the file named publish.js inside the new myTemplate folder and replace "Home" with "MyDescription". Two points to note here: the file name has to remain publish.js, and "Home" appeared in two places in my original "publish.js", in the line 
    var nav = '<h2><a href="index.html">Home</a></h2>';
    and the line starting generate('Home',....

  4. Tell the jsdoc generator where to find your custom template (myTemplate folder) and your overview file ("README.md"). You can add -t pathTo\myTemplate to the command line, or you can use a very short command line, jsdoc -c pathTo\conf.json if you create a file named conf.json in a text editor, something like the file below, which specifies the source, destination, etc. for the documentation. That file puts the overview into the main page by telling the doc generator to use README.md in the "source" section, and changes the headings from "Home" to the new heading, "MyDescription", using the new myTemplate folder in the "opts" section.

    {
    "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
    }
}
有趣的答案。但是，由于在项目根目录下有一个README.md文件，我尝试了pathTo/README.md：README.md，./README.mf...但我总是收到文件未找到的错误。很遗憾JSDoc文档不是非常详细... - FrViPofm
通过将路径添加到README.md中，问题得到了解决，也许你应该在项目根文件夹中拥有readme文件？然后include只需要["...", "README.md"]，因为它与根目录相同。 - Joel Carneiro
5
您还可以在一个或多个源文件中添加 @file（或 @fileOverview）。
所有文件的概述部分都将包含在 JSDoc 主页中。如果您还将README文件提供给JSDoc，则文件概述将放置在README内容之后。
例如：
/**
 * @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>
 */
3

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

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

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

然后我编辑了layout.tmpl文件，添加了一个<style>标签，并设置了一个样式规则，该规则不显示到home.html页面的链接：

nav > h2 {
  display: none;
}
3

在默认模板中，“Home”是硬编码的（在生成索引时作为 title 传递），因此没有变量或配置可供修改此标题。

如果有多个人生成/编辑文档，则编辑 node_modules 显然是不可行的。

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

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接