Live docs on top of dgeni documentation generator
Dgeni-alive
documentation generator has been built after a long search for working one with AngularJS doc flavour.
With dgeni-alive you can
Parts of code were taken from generator-ngdoc.
npm install dgeni-alive --save-dev
var docgen = require('../scr/docgen')();
docgen.package().config(function(log) {
log.level = 'info';
})
.src(this.filesSrc);
.dest(this.data.dest);
.generate().then(function(){
console.log("I'm done!");
});
Load task
grunt.loadNpmTasks('dgeni-alive');
Add section to your Gruntfile.js
"dgeni-alive": {
options: {
// optional basePath for correct path calculation
basePath: '',
// optional dgeni packages
packages: [
'dgeni-packages/jsdoc', // either names
require('dgeni-packages/examples') // or packages
]
// optional serve section for running local http server with live docs
serve: {
// the server port
// can also be written as a function, e.g.
port: 10000,
// open the browser
openBrowser: true // or command to run favorite browser
}
},
api: {
// product title
title: 'My Docs',
// product version
version: '<%= pkg.version %>',
// do not expand paths
expand: false,
// where to put docs
dest: '/docs/',
// where to look for sources
// grunt globbing is supported
src: [
'/src/**/*.js',
'!**/test/**/*.js'
],
// Any paths that contain your overriden templates relative to the grunt file
templatePaths: [
'dgeniAliveTemplates'
]
}
Add the dgeni-packages examples package to your package array. If you want the "Edit in Plunker" button and file tabs also add dgeni-alive examples-ext. Your package array should look something like this:
packages: [
'dgeni-packages/ngdoc',
'dgeni-packages/examples',
'./packages/examples-ext',
],
You will also need to add deployments configuration to generate the examples. This is added to the "options" section of the configuration.
deployments: [{
name: 'default',
examples: {
commonFiles: {
scripts: [
'https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js',
'docs/resources/js/examples.js'
],
stylesheets: []
}
}
}],
deploymentTarget: 'default'
This example configuration defines a deployment "default" and makes it the default target. It tells every example to include jquery and a js file relative to the build path called "examples.js". Paths that do not begin with http(s), // or / will be copied automatically in the same place as the generated example html if you use "examples-ext" package. You could also specify stylesheets in the stylesheets array.
iFrame-Resizer (https://github.com/davidjbradshaw/iframe-resizer) is used to resize example iframes when "examples-ext" is used. The following options for iframe resizer may be specified as example attributes (see iframe-resizer readme for explainations of what they do): log, minHeight, maxHeight, heightCalculationMethod, scrolling, tolerance. Options are set as attributes in your example tag in the documentation as snake-case with frame- prefixed before the option name. This is an example of setting minHeight to 200:
* <example module="myModule" name="myExample" frame-min-height="200">
If you wish to disable iframe-resizer for an example add frame-no-resize="true"
to your example.
dgeni-alive provides several packages to supplement the default dgeni-packages.
To include a package from dgeni-alive in grunt configuration you would add ./packages/{package-name}
to you packages array.
MIT