如何为GitHub Pages生成JavaScript API文档

Question

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

我还想将代码URL链接到GitHub本身.我发现jsdoc-githubify会使输出更改链接,但我更喜欢一个更直接的选项,我有更多的控制权.

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

Answer 1

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

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

请参阅下面的Gruntfile示例.
请注意,这支持所有JSDoc CLI选项.

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风格的markdown文件(还有一个Grunt插件grunt-jsdoc2md),然后相应地配置一个Jekyll项目.

但请注意,您需要做一些额外的工作来安装和配置Jekyll.这是一篇很好的文章和一个示例项目.

更新:

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

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

请参阅此处的Docma文档,该文档也是使用Docma构建的,并托管在GitHub页面上.

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

Answer 2

我认为这就是你要找的:http://jsdox.org/

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