Add JSDoc HTML output and fix JSDoc tags

[mtraynham]

I've added HTML JSDoc output. It dumps to ./web/docs/html, with the main html file dc.html. During this exercise, I realized that using the @name annotation was not completely correct in most cases, and should have been @namespace for nested objects off dc's root and @method for functions.

There are two outstanding issues with this.

1. The source paths that point back to the code, are absolute. I believe it's tied to grunt-jsdoc and this bug:
   Absolute paths used on Windows krampstudio/grunt-jsdoc#135
2. It say's DocStrap in the title bar, but maybe we can change this to "dc".

I didn't actually check in the generated files, but I figured you could do that @gordonwoodhull since it may make merging up to develop harder with the api-latest.md being changed as well.

Attaching some pictures 😄

[gordonwoodhull]

This looks great and I'm going to merge it, but it's definitely a work-in-progress, so I'm going to see if I can avoid publishing the generated output for now. (We'll see if grunt web allows that.)

Random observations (I haven't looked very thoroughly):

• the parameters for the chart pseudo-classes are gone (maybe a namespace isn't supposed to have parameters?). The return value is gone too but that isn't very helpful anyway.
• using namespace for our pseudo-classes means that they appear in a Namespaces menu at the top
• it drops relative links - we use lots of {@link #dc.coordinateGridMixin+brushOn} because we don't know the absolute URL where docs will be hosted. JSDoc or DocStrap just keeps the text and throws out the link.
• the source links are nice but they link to the generated dc.js not the source files. It apparently also uses the local path where you are building, so I get beautifully formatted source files named e.g. -_Users_gordon_src_dc.js_dc.js.html
• DocStrap is a rather unfortunate name, so I hope we can change the title 😦

[gordonwoodhull]

Oh I see you linked to an issue about the absolute paths. It's weird that we would see that on OSX when the developer is on Linux and the other reporters are on Windows.

[gordonwoodhull]

Merged in 2.0 beta 26. Thanks @mtraynham!

[mtraynham]

@gordonwoodhull No worries, there is a way we can configure the documents to remove the "DocStrap" stuff. I believe we need a config file like:
https://github.com/docstrap/docstrap/blob/master/template/jsdoc.conf.json
Maybe:

{
  "tags": {
    "allowUnknownTags": true
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "logoFile": "",
    "cleverLinks": false,
    "monospaceLinks": false,
    "dateFormat": "ddd MMM Do YYYY",
    "outputSourceFiles": true,
    "outputSourcePath": true,
    "systemName": "dc.js",
    "footer": "",
    "copyright": "dc.js Copyright © 2012-2016 Copyright 2012-2016 Nick Zhu & the dc.js Developers",
    "navType": "vertical",
    "theme": "cosmo",
    "linenums": true,
    "collapseSymbols": false,
    "inverseNav": true,
    "protocol": "html://",
    "methodHeadingReturns": false
  },
  "markdown": {
    "parser": "gfm",
    "hardwrap": true
  }
}

And then you specify this in the Grunt spec:

jsdoc : {
    dist : {
        options: {
              ....
              configure : "./jsdoc.conf.json"
        }
    }
}

[mtraynham]

In regards to that source path bug (krampstudio/grunt-jsdoc#135), I did find that if you pre-concatenated everything it worked. But that made the source lookup extremely slow because it was all attached to one file instead of multiple...

Also, maybe there is a different decorator to work with the namespaces, I just didn't find one...

[gordonwoodhull]

Looks good, hope to try the config file soon.

I'm sure the other problems are solvable too, it's just that these are big old tools and it's a lot of work just to figure out how to use them right.

The docs are getting big, so pagination is going to be helpful.

[gordonwoodhull]

Thanks @mtraynham, the config helps. I'll open issues for the other problems.

It was nice to hear from @75lb on #1054 and start to understand why our markdown documentation may not be working so well inside the GitHub UI. I'm thinking that we should stop trying to use GitHub as our documentation viewer!