如何为GitHub Pages生成JavaScript API文档

There are a lot of great options for generating API documentation for other languages, but I have yet to find a solution for my JavaScript API that I want to host on GitHub Pages. It seem that I can use JSDoc3 but I would need to create a custom plugin that outputs Jekyll markup.

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

I would also like the code URLs to link to GitHub itself. I found jsdoc-githubify that will munge the output to change the links, but I'd prefer a more straightforward option where I have more control.

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

Do I have to create my own JSDoc plugin, or is there a better solution out there that I've missed. What do folks use for this?

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

6 个解决方案

#1

If you're familiar with Grunt, you can easily generate .html docs with grunt-jsdoc.

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

Document your code with JSDoc.

使用JSDoc记录您的代码。

Use grunt-jsdoc which internally uses jsdoc to generate code documentation.

使用grunt-jsdoc,它在内部使用jsdoc生成代码文档。

This will also output the source code in HTML and within the documentation it will include links to code lines for each publicly accessible member.

这也将以HTML格式输出源代码,在文档中,它将包含每个可公开访问的成员的代码行链接。

You can also have control on the links by simply using the @link directive of JSDoc:
See {@link https://github.com/onury|My GitHub Profile}.

您也可以通过简单地使用JSDoc的@link指令来控制链接:请参阅{@link https://github.com/onury|My GitHub Profile}。

See a Gruntfile example below.
Note that this supports all JSDoc CLI options.

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

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

And you run this task with grunt jsdoc. Or you can add the grunt-contrib-watch plugin to auto-run each time the file changes.

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

Templates and Styling:

模板和样式:

You can always play with the CSS file and overwrite it for your own taste.

您可以随时使用CSS文件并根据自己的喜好覆盖它。

Or you can use docstrap template for JSDoc3 based on Bootstrap which can be used with grunt-jsdoc.

或者您可以使用基于Bootstrap的JSDoc3的docstrap模板,它可以与grunt-jsdoc一起使用。

Using Jekyll for documentation:

使用Jekyll获取文档:

Although it's natively supported, you do not have to use Jekyll for GitHub Pages. Jekyll is actually designed for static websites or blogs. But it can take markdown files. So, I'd first create github flavoured markdown files from code via jsdoc-to-markdown (there is also a Grunt plugin grunt-jsdoc2md) then configure a Jekyll project accordingly.

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

But note that you'll need to do some extra work to install and configure Jekyll. Here is a good article and a sample project to start with.

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

UPDATE:

After answering this, I started working on a tool for building documentation easily. Now, it's mature enough to post here and see if you like it. It's called Docma.

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

Key Docma features are; it can both parse JSDoc and Markdown files into HTML documentation, generates a web-app, extremely configurable and works great with Github Pages.

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

See Docma documentation here, which is also built with Docma and hosted on GitHub Pages.

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

A sample screenshot of Docma generated SPA:

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

#2

I think this is what you are looking for: http://jsdox.org/

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

jsdox is a simple jsdoc 3 generator. It pulls documentation tags based on a subset of jsdoc 3 from your javascript files and generates markdown files.

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

#3

JSDox is exactly what you are looking for.

JSDox正是您所需要的。

#4

I'm a fan of swagger: https://github.com/swagger-api/swagger-ui & http://swagger.io/.

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

It includes more than just API documentation so maybe it's overkill for you but it does a beautiful job of documenting APIs.

它不仅仅包含API文档,所以它可能对你来说太过分了,但是它可以很好地记录API。

#5

Though I haven't updated it in a while, https://github.com/punkave/dox-foundation is another option. It will just generate HTML files that you could commit to your gh-pages branch.

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

#6

trying to simplify it

试图简化它

In GitHub pages generating API documentation that outputs Jekyll markup.

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

Escape liquid template with {% raw %} tag.

使用{%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

create two branch, one for master one for gh-pages, master branch contain your .md file and gh-pages contain static generated .html file. In local computer: $ jekyll build in current project folder will be generated into ./_site.

创建两个分支,一个用于gh页面的主分支,master分支包含.md文件,gh-pages包含静态生成的.html文件。在本地计算机中:$ jekyll build in current project folder将生成为./_site。

upload to GitHub.

上传到GitHub。
jekyll
- master branch: github/.com/jekyll/jekyll
- gh-pages branch: github/.com/jekyll/jekyll/tree/gh-pages
fb/react
- master branch: github/.com/facebook/react/edit/master/docs/docs/ref-01-top-level-api.md
- gh-pages branch: github/.com/facebook/react/blob/gh-pages/docs/top-level-api.html

Pages URLs link to GitHub document itself.

Pages URL链接到GitHub文档本身。

In _layouts folder (html template) Add link "Edit on GitHub" on docs pages this is blog post about it

在_layouts文件夹(html模板)在文档页面上添加链接“在GitHub上编辑”这是关于它的博客文章

#1