search

steveush / foodoc

A Bootstrap and Handlebars based JSDoc3 template.
GNU General Public License v3.0
23 stars 14 forks source link

readme

NPM

Dependency Status devDependency Status Donate

FooDoc

FooDoc is a Bootstrap and Handlebars based template for JSDoc3. A big thanks must go out to DocStrap as it served as the inspiration for this project.

This project began as a simple modification of DocStrap. Removing the Bootswatch support in favor of my own CSS customizations but it ended up with me re-writing pretty much the entire template, even switching out the template engine to Handlebars.

Features

What it looks like

As this started off as a DocStrap modification I've used it's fixtures code to generate the sample documentation so you can compare the differences between the two.

NOTE: The fixtures code doesn't make use of the @summary tag when describing it's members so it may look a little sparse.

Ooooh, I want it! How do I get it?

If you manage your own version of jsdoc:

npm install foodoc

When using grunt, please look at grunt-jsdoc which you can use with FooDoc.

Command line example

jsdoc -c path/to/conf.json -t ./node_modules/foodoc/template -R README.md -r .

The -c sets the config, the options you can supply in the templates object are listed below in the options.

The -t sets the template. This is the option you need to set to get the FooDoc template to be used.

The -R sets a markdown file to be the front page of the documentation.

The -r tells jsdoc to run recursively.

The . says from current directory.

Configuring the template

FooDoc ships with a conf.json file in the template/ directory. It is just a regular old JSDoc configuration file, but with the following new options:

"templates": {
    "systemName"            : "{string}",
    "systemSummary"         : "{string}",
    "systemLogo"            : "{string}",
    "systemColor"           : "{string}",
    "footer"                : "{string}",
    "copyright"             : "{string}",
    "includeDate"           : "{boolean}",
    "dateFormat"            : "{string}",
    "inlineNav"             : "{boolean}",
    "inverseNav"            : "{boolean}",
    "navMembers"            : "{array.<object>}",
    "linenums"              : "{boolean}",
    "showTableOfContents"   : "{boolean}",
    "showAccessFilter"      : "{boolean}",
    "analytics"             : "{object}",
    "collapseSymbols"       : "{boolean}",
    "methodHeadingReturns"  : "{boolean}",
    "outputSourceFiles"     : "{boolean}",
    "outputSourcePath"      : "{boolean}",
    "sort"                  : "{boolean|string}",
    "search"                : "{boolean}",
    "favicon"               : "{string}",
    "stylesheets"           : "{array.<string>}",
    "scripts"               : "{array.<string>}"
}

Options

Extended tutorial configuration

JSDoc supports providing a .json file in your tutorials directory to configure the hierarchical structure and title for tutorials. This template adds two new options to each tutorial in this file.

The following shows what the tutorials.json in the fixtures test code contains.

NOTE: The array based syntax for child tutorials is not supported at present and children must be supplied as properties of an object.

{
  "brush-teeth": {
    "title": "Brush Teeth",
    "summary": "How to brush your teeth!",
    "children": {
      "fence-test": {
        "title": "Fence Test",
        "summary": "Testing syntax highlighting.",
        "showTableOfContents": false
      }
    }
  },
  "drive-car": {
    "title": "Drive Car",
    "summary": "How to drive a car!"
  }
}

Syntax highlighting

FooDoc uses Prism to provide syntax highlighting and supports a couple of ways to specify which language to use.

If you need to use a language provided by a Prism plugin you will need to fork the template and add in the specific language yourself. Take a look at the Prism documentation to see a full list of all 119 supported languages.

FAQ

Why another template?

Over the years I have tried quite a few templates available for JSDoc and none of them produced a look I was quite happy with. Some got close like DocStrap, but I still wasn't quite satisfied so I did what all developers do eventually, roll their own. I really liked the clean look of the Bootstrap 3 documentation so I used it as base for the layout and styling for this template.

Why Handlebars?

Personal preference really, Underscore templates work great but due to there ability to have basically any JavaScript in them I've noticed a lot logic which should be handled elsewhere creep into them overtime. It's simply easier to hack it into the template than find where it should be implemented as part of the post processing.

What's different from DocStrap's search?

The lunr search implementation in DocStrap performs all the indexing in the browser using a hidden iframe, this was done to allow the search to work offline when viewing the documentation via the file:// protocol. It does however have the drawback of loading and then indexing what could potentially be a large numbers of documents, on every page load.

While this works I took a different approach and decided to generate the search index and store as part of the documentation process and output the results in two files lunr-data.json and lunr-data.js. These two files are then consumed by the search component when required. The lunr-data.json file is fetched via ajax request if the documentation is served via http:// or https:// protocols while the lunr-data.js file is simply included into the page when using the file:// protocol as you can't perform ajax requests. This ultimately provides us with two primary benefits over DocStrap's implementation:

  1. All indexing of documents is performed only once, when the documentation itself is generated. Due to creating the index directly from the JSDoc doclets it contains more detailed information, including information on members, methods and type definitions, leading to better search results where you can click on a method name and be taken directly to it's documentation.
  2. The index and store information is only loaded into the page when a user performs a search, this greatly improves load speeds.

The following shows the lunr index fields implemented by this template:

var index = lunr(function(){
    this.field('longname', {boost: 1000});
    this.field('name', {boost: 500});
    this.field('tags', {boost: 300});
    this.field('kind', {boost: 110});
    this.field('title', {boost: 100});
    this.field('summary', {boost: 70});
    this.field('description', {boost: 50});
    this.field('body');
    this.ref('id');
});

Why Prism instead of Sunlight?

Quite simply Sunlight is no longer maintained and while it does work I prefer Prism which is actively maintained and follows HTML5 standards.

To Do

Changelog

All releases prior to 1.0.0 are considered pre-release, i.e. I'm not finished changing stuff yet so anything can happen ;)

0.0.9

0.0.8

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

0.0.1