Question

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

我还想将代码URL链接到GitHub本身。我发现jsdoc-githubify会使输出更改链接，但我更喜欢一个更直接的选项，我可以更好地控制。

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

Answer 1

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

使用JSDoc记录您的代码。
使用grunt-jsdoc在内部使用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的JSDoc3 docstrap模板，该模板可以与grunt-jsdoc一起使用。

使用Jekyll作为文档：

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

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

更新：

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

主要Docma功能是;它既可以将 JSDoc 和 Markdown 文件解析为HTML文档，也可以生成一个非常可配置的Web应用程序，并且可以与 Github页面一起使用。

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

Docma生成SPA的示例屏幕截图：

Answer 2

我认为这正是您所寻找的：http://jsdox.org/

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

Answer 3

JSDox正是您所寻找的。

Answer 4

我是一个狂热的粉丝：https://github.com/swagger-api/swagger-ui＆amp; http://swagger.io/。

它不仅仅包含API文档，所以它可能对你来说太过分了，但它在记录API方面做得很好。

Answer 5

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

Answer 6

试图简化它

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

使用{% raw %}标记转出液体模板。
```
{% raw %}
   I want to be {{escaped}}.
{% endraw %}
```
ref：github / .com / Shopify / liquid / wiki / Liquid-for-Designers＃raw

ref：jekyllrb / .com / docs / github-pages / #project-pages

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

上传到GitHub。
化身
- master branch：github / .com / jekyll / jekyll
- gh-pages branch：github / .com / jekyll / jekyll / tree / gh-pages
FB /反应
- master branch：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

页面网址链接到GitHub文档本身。

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

如何为GitHub Pages生成JavaScript API文档

6 个答案: