dgeni-alive v0.4.1
dgeni-alive
Live docs on top of dgeni documentation generator
Motivation
Dgeni-alive
documentation generator has been built after a long search for working one with AngularJS doc flavour.
- ngdocs (grunt-ngdoc, grunt-ngdocs, etc) - has no updates for a long time
- docular - has no activity as well
- generator-ngdoc - has no activity as well and forces to use Yeoman tools, is not suitable for CI
- sia - really good one, but it likes Gulp and does not provide standalone extensible generator
With dgeni-alive you can
- Use docgen as grunt task and directly
- Extend docgen like native Dgeni package
- Configure web views
- TBD: view live examples
Parts of code were taken from generator-ngdoc.
Demo Projects
What's Done
- Migrated to Angular 1.5
- Added controller and factory templates
- Added links to internal/external components and types to method params
- Added api-index component to show title API page
- Added @deprecated, @since and @access tags
- Built-in docs server
- Added Errors Reference
- Added Search
- Added @sortOrder tag
- Added JSX reader and @ngdoc type 'React' for documenting React components.
- TBD
How it works
- Configure Dgeni package
- Append custom processors/templates/filters/etc
- Run dgeni generator
- Serve built app with your favorite server
- ...
- Profit
How to use
Install
npm install dgeni-alive --save-dev
API
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!");
});
Grunt task
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'
]
}
Setting up Live Examples
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.
Configuring iFrame-Resizer
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.
Additional Packages
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.
- examples-ext: provides improvements to the live examples
- jsdoc-ext: provides additional jsdoc tags and code expressions (included by default)
- jsx: provides jsx support
- links-ext: provides extensions to dgeni-packages/links (included by default)
- ngdoc-ext: provides extensions to dgeni-packages/ngdoc (included by default)
- website: website package (included by default)
License
MIT
8 years ago
8 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago