grunt-processdocstrapdocs

grunt-processdocstrapdocs

Post-process generated JSDoc documentation based on docstrap templates.

Issues Addressed

Some issues with the generated templates are:

• There are may relative URLs in the generated documation CSS and HTML files, such as all CSS files starting with an @import url('//fonts.googleapis.com/...') import statement, which results in a relative path to the URL. That means when docs are loaded locally, the resulting absolute path uses a file:// protocol, which means the fonts fail to load -- which, depending on the system, can take a really long time (to resolve an invalid URL) and be really annoying when navigating the documentation.

  This is specifically logged as https://github.com/terryweiss/docstrap/issues/26

  This issue is fixed by converting all URLs to absolute paths, as configured.

• The templates use the navbar-fixed-top style to keep the top toolbar visible while scrolling vertically, but when clicking on an inline link (e.g. a method for the class being viewed), the page scrolls to the right location but the method's name and signature end-up hidden behind the fixed top navbar/toolbar.

  In reality, this issue could/should be handled by customizing your template, but in my case, that seemed like a lot of work when this quick post-processing would do the trick. This option is disabled by default.

  This issue is fixed by removing the navbar-fixed-top style from the top navbar.

  Note: Later releases of built-in JSDoc templates have addressed this issue so setting this option is no longer necessary (at least as of JSDoc 3.3.2 or even earlier).

Note: For this task, each source is also a destination. Destinations are ignored (i.e. modifiations will be made to each source directory specified).

Big thanks to Terry Weiss (and contributors) for really nice JSDoc templates at https://github.com/terryweiss/docstrap!

Installation

npm install grunt-processdocstrapdocs --save-dev

Configuration

//// gruntfile.js:

grunt.initConfig({
  jsdoc: {
    // your existing configuration
  },
  processdocstrapdocs: {
    options: {
      fixProtocol: true,
      protocol: 'http',
      fixTopNavbar: true
    },
    dist: {
      src: 'docs'
    }
  }
});

grunt.registerTrask('docs', ['jsdoc', 'processdocstrapdocs']);

//// command line:

$ grunt docs

Note that the processdocstrapdocs task must depend on the jsdoc task, that your jsdoc task is expected to be configured to use one of the provided ink-docstrap templates.

Settings

src

{(String|Array.<String>)} src (required)

The directory (String), or list of directories (Array.<String>), that contain generated JSDoc documentation based on an ink-docstrap template.

Options

fixProtocol

{Boolean} [fixProtocol=true] (optional, default: true)

Fix the relative protocols, changing them all to use the value of the protocol option.

protocol

{String} [protocol='http'] (optional, default: 'http')

Protocol to use when fixing relative protocols with fixProtocol enabled.

fixTopNavbar

{Boolean} [fixTopNavbar=false] (optional, default: false)

Fix the top navbar issue by letting it scroll with content.

This option is false by default since this really should be handled by customizing your template and the latest version of JSDoc (3.3.2 at this time) has fixed the issue in their built-in templates.

TODO

• add some real tests