How can I generate JavaScript API documentation for GitHub Pages [closed]

Question

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.

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.

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?

Answer 1

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

• Document your code with JSDoc.
• Use grunt-jsdoc which internally uses jsdoc to generate code documentation.
• 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.
• 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}.

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

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.

Templates and Styling:

• You can always play with the CSS file and overwrite it for your own taste.
• Or you can use docstrap template for JSDoc3 based on Bootstrap which can be used with grunt-jsdoc.

Using Jekyll for documentation:

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.

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.

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.

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.

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

A sample screenshot of Docma generated SPA:

Answer 2

I think this is what you are looking for: 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.