grunt-processdocstrapdocs
v0.0.3
Published
Post-process generated JSDoc documentation based on docstrap templates.
Downloads
9
Maintainers
Readme
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 afile://
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