如何为 GitHub Pages 生成 JavaScript API 文档 [关闭]

Question

为其他语言生成 API 文档有很多不错的选择，但我还没有找到我想要在 GitHub Pages 上托管的 JavaScript API 的解决方案。看来我可以使用JSDoc3，但我需要创建一个输出 Jekyll 标记的自定义插件。

我还希望将代码 URL 链接到 GitHub 本身。我发现jsdoc-githubify 可以修改输出以更改链接，但我更喜欢更直接的选项，我有更多的控制权。

我是否必须创建自己的 JSDoc 插件，或者是否有我错过的更好的解决方案。人们为此使用什么？

Answer 1

如果您熟悉Grunt，您可以使用grunt-jsdoc 轻松生成.html 文档。

• 使用JSDoc记录您的代码。
• 使用内部使用jsdoc 的grunt-jsdoc 生成代码文档。
• 这还将以 HTML 格式输出源代码，并且在文档中它将包含指向每个可公开访问成员的代码行的链接。
• 您还可以通过简单地使用 JSDoc 的 @link 指令来控制链接：
  See {@link https://github.com/onury|My GitHub Profile}。

请参阅下面的 Gruntfile 示例。
请注意，这支持所有JSDoc CLI options。

grunt.initConfig({
    'jsdoc': {
        dist: {
            src: ['./src/core/mylib.js'],
            options: {
                destination: './doc/html'
            }
        }
    }
});

您使用grunt jsdoc 运行此任务。或者您可以添加grunt-contrib-watch 插件以在每次文件更改时自动运行。

模板和样式：

• 您可以随时使用 CSS 文件并根据自己的喜好覆盖它。
• 或者您可以使用基于 Bootstrap 的 docstrap JSDoc3 模板，该模板可与 grunt-jsdoc 一起使用。

将Jekyll 用于文档：

虽然它是本机支持的，但您不必将 Jekyll 用于 GitHub Pages。 Jekyll 实际上是为静态网站或博客设计的。但它可以采用降价文件。因此，我首先通过 jsdoc-to-markdown（还有一个 Grunt 插件 grunt-jsdoc2md）从代码创建 github 风格的降价文件，然后 configure 相应地创建一个 Jekyll 项目。

但请注意，您需要做一些额外的工作来安装和配置 Jekyll。这是一个很好的 article 和一个 sample project 开始。

更新：

在回答完这个问题后，我开始研究一种用于轻松构建文档的工具。现在，它已经足够成熟了，可以在这里发帖，看看你是否喜欢它。它被称为Docma。

Docma 的主要功能是；它可以将 JSDoc 和 Markdown 文件解析为 HTML 文档，生成一个 web 应用程序，非常可配置，并且可以很好地与 Github Pages 配合使用。 p>

请参阅Docma documentation here，它也是使用 Docma 构建并托管在 GitHub Pages 上。

Docma 生成的 SPA 示例截图：

Answer 2

尽量简化

• 在生成输出 Jekyll 标记的 API 文档的 GitHub 页面中。

  带有{% raw %}标签的转义液体模板。

  {% raw %}
     I want to be {{escaped}}.
  {% endraw %}
  

  参考：github/.com/Shopify/liquid/wiki/Liquid-for-Designers#raw

  参考：jekyllrb/.com/docs/github-pages/#project-pages

  创建两个分支，一个用于主分支，一个用于 gh-pages， master 分支包含您的 .md 文件，而 gh-pages 包含静态生成的 .html 文件。 在本地计算机中：当前项目文件夹中的$ jekyll build将生成为./_site。

  上传到 GitHub。

  杰基尔

  • master 分支：github/.com/jekyll/jekyll
  • gh-pages 分支：github/.com/jekyll/jekyll/tree/gh-pages

  脸书/反应

  • master 分支：github/.com/facebook/react/edit/master/docs/docs/ref-01-top-level-api.md
  • gh-pages 分支：github/.com/facebook/react/blob/gh-pages/docs/top-level-api.html

页面 URL 链接到 GitHub 文档本身。

在_layouts 文件夹中（html 模板） 添加链接"Edit on GitHub" on docs pages这是blog post about it

Answer 3

JSDox 正是您要找的。​​p>

Answer 4

我是 swagger 的粉丝：https://github.com/swagger-api/swagger-ui & http://swagger.io/。

它不仅包含 API 文档，因此对您来说可能有点过头了，但它在记录 API 方面做得很好。

Answer 5

虽然我有一段时间没有更新它，但https://github.com/punkave/dox-foundation 是另一种选择。它只会生成可以提交到gh-pages 分支的HTML 文件。

Answer 6

我想这就是你要找的东西：http://jsdox.org/

jsdox 是一个简单的 jsdoc 3 生成器。它从您的 javascript 文件中提取基于 jsdoc 3 子集的文档标签并生成降价文件。