Documentation Generation on Steroids!

who am i?Pete Bacon Darwin

surname

dgeni - today

● why does it exist?● what does it do?● how does it work?● what's in it for me?

Q1. AngularJSWhat's the syntax of the method on $sce to

declare a string of HTML to be trusted

A1. AngularJS$sce.trustAsHtml(value)

https://docs.angularjs.org/api/ng/service/$sce#trustAsHtml

Q2.ProtractorHow do I access the second row of this repeater?<div ng-repeat="cat in pets">

A1. Protractorelement(by.repeater('cat in

pets').row(1))

http://angular.github.io/protractor/#/api?view=ProtractorBy.prototype.repeater

Q3. Ionic FrameworkName the directive to for refreshing the display

when you swipe down

A3. Ionic Framework<ion-refresher></ion-refresher>

http://ionicframework.com/docs/api/directive/ionRefresher/

love the docs

http://fav.me/d5a5rg8

hate stale docs

AngularJS docs

ngdoc - the tags

ngdoc - the code

photo © Daniel Steger for openphoto.net)

https://github.com/angular/angular.js/blob/c086f831f/docs/src/ngdoc.js

thus came dgeni(https://github.com/angular/dgeni)

project goals:● apply good design principles● configurable processors & services● using dependency injection● fully tested code-base

projects using dgeni

● AngularJS

● Protractor

● Angular Material

● Ionic Framework

AngularJS

https://docs.angularjs.org

● AngularJS container app● each doc is a partial HTML file● displayed by an ngInclude directive● dgeni config ~500 LOC

Protractor

angular.github.io/protractor/#/api

● AngularJS container app● docs are stored in a single JSON file● filtered and displayed by a Controller● also generates docs from webDriver source● dgeni config ~250 LOC

angular material

https://material.angularjs.org/#

● AngularJS container app● each doc is a mini Angular app● displayed in an iframe● dgeni config ~400 LOC

ionic framework

http://ionicframework.com/docs/

● Jekyll hosted static app● each doc is a markdown file● dgeni config ~245 LOC

● Processors - building blocks of doc generation● Services - singleton helper objects● Packages - reusable component containers

dgeni - key concepts

doc processor pipeline

write files

extract tags

render content

docs

read files

docs

docs

sourcefiles

outputfiles

dependency injection

Everything in dgeni is an injectable component created by a factory function:● processors● services● config blocks(similar to AngularJS)

creating packages

processors, services, config and templates are grouped into packages:var p = new Package('docPackage', ['jsdoc']).factory(require('./services/myService') .processor(require('./processors/myProcessor').config(function(templateFinder) { templateFinder.templateFolders = ['./templates'];});

defining services

Simply export a factory function from a module:

module.exports = function log() { return function(message) { console.log(message); };};

module.exports = function filterNgDocsProcessor(log) { return { $runAfter: ['tags-parsed'], $runBefore: ['extracting-tags'], $process: function(docs) { var filteredDocs = _.filter(docs, function(doc) { return doc.tags.getTag('ngdoc'); }); log.debug('filtered '+(docs.length-filteredDocs.length)); return filteredDocs; } };};

processors

running dgeni

var Dgeni = require('dgeni');var myPackage = require('./myPackage);var dgeni = new Dgeni([myPackage]);dgeni.generate().then(function() { ...});

dgeni-packages(https://github.com/angular/dgeni-packages)

reusable packages for dgeni● base - basic document processing● jsdoc - JSDoc style @tags● nunjucks - template based rendering ● ngdoc - processing for the AngularJS project● examples - inline runnable examples (and tests)

documenting your apps

customize the generation

● Provide your own templates● Add extra processors● Provide a container application

coding challenge

● create a new cool set of templates for the demo

https://github.com/petebacondarwin/dgeni-angular

Get dgeni

cd your-projectnpm install --save-dev dgeni dgeni-packages

https://github.com/angular/dgenihttps://github.com/angular/dgeni-packageshttps://github.com/petebacondarwin/dgeni-angularhttps://github.com/petebacondarwin/dgeni-example

Matias NiemeläNate Wilkins

Donald PipowitchJeff Cross

Andres Dominguez Jeremy Attali

Michael J. ZoidlThor JacobsenLucas GalfasoTim Kendrick

thank you

Stéphane ReynaudAndy Joslin

Pascal PrechtJulie Ralph

Jim Cumminsthorn0

Kevin RoweMatthew Harris

Konstantinos RousisTobias Bosch

templates (nunjucks package)

http://mozilla.github.io/nunjucks/

document

templates

renderedcontent