grunt-processdocstrapdocs

 


Post-process generated JSDoc documentation based on docstrap templates.

Issues Addressed

Some issues with the generated templates are:

1. 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.

2. 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.

$3

#### src

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

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

$3

#### 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