0.4.1 • Published 8 years ago

dgeni-alive v0.4.1

Weekly downloads
74
License
MIT
Repository
github
Last release
8 years ago

dgeni-alive

Live docs on top of dgeni documentation generator

[ FAQ ] [ HowTo ]

Motivation

Dgeni-alive documentation generator has been built after a long search for working one with AngularJS doc flavour.

  1. ngdocs (grunt-ngdoc, grunt-ngdocs, etc) - has no updates for a long time
  2. docular - has no activity as well
  3. generator-ngdoc - has no activity as well and forces to use Yeoman tools, is not suitable for CI
  4. sia - really good one, but it likes Gulp and does not provide standalone extensible generator

With dgeni-alive you can

  1. Use docgen as grunt task and directly
  2. Extend docgen like native Dgeni package
  3. Configure web views
  4. TBD: view live examples

Parts of code were taken from generator-ngdoc.

Demo Projects

  1. angular-route-segment, sources
  2. angular-gettext, sources
  3. TBD

What's Done

  1. Migrated to Angular 1.5
  2. Added controller and factory templates
  3. Added links to internal/external components and types to method params
  4. Added api-index component to show title API page
  5. Added @deprecated, @since and @access tags
  6. Built-in docs server
  7. Added Errors Reference
  8. Added Search
  9. Added @sortOrder tag
  10. Added JSX reader and @ngdoc type 'React' for documenting React components.
  11. TBD

How it works

  1. Configure Dgeni package
  2. Append custom processors/templates/filters/etc
  3. Run dgeni generator
  4. Serve built app with your favorite server
  5. ...
  6. 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

0.4.1

8 years ago

0.4.0

8 years ago

0.3.5

9 years ago

0.3.4

9 years ago

0.3.2

9 years ago

0.3.1

9 years ago

0.2.1

9 years ago

0.2.0

9 years ago

0.1.9

9 years ago

0.1.8

9 years ago

0.1.7

9 years ago

0.1.6

9 years ago

0.1.5

10 years ago

0.1.4

10 years ago

0.1.3

10 years ago

0.1.2

10 years ago

0.1.1

10 years ago

0.0.10

10 years ago

0.0.9

10 years ago

0.0.8

10 years ago

0.0.7

10 years ago

0.0.6

10 years ago

0.0.5

10 years ago

0.0.4

10 years ago

0.0.3

10 years ago

0.0.2

10 years ago

0.0.1

10 years ago