Dgeni documentation generator
-
Upload
peter-darwin -
Category
Technology
-
view
432 -
download
7
description
Transcript of Dgeni documentation generator
![Page 1: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/1.jpg)
Documentation Generation on Steroids!
![Page 2: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/2.jpg)
who am i?Pete Bacon Darwin
surname
![Page 3: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/3.jpg)
dgeni - today
● why does it exist?● what does it do?● how does it work?● what's in it for me?
![Page 4: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/4.jpg)
Q1. AngularJSWhat's the syntax of the method on $sce to
declare a string of HTML to be trusted
![Page 5: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/5.jpg)
A1. AngularJS$sce.trustAsHtml(value)
https://docs.angularjs.org/api/ng/service/$sce#trustAsHtml
![Page 6: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/6.jpg)
Q2.ProtractorHow do I access the second row of this repeater?<div ng-repeat="cat in pets">
![Page 7: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/7.jpg)
A1. Protractorelement(by.repeater('cat in
pets').row(1))
http://angular.github.io/protractor/#/api?view=ProtractorBy.prototype.repeater
![Page 8: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/8.jpg)
Q3. Ionic FrameworkName the directive to for refreshing the display
when you swipe down
![Page 9: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/9.jpg)
A3. Ionic Framework<ion-refresher></ion-refresher>
http://ionicframework.com/docs/api/directive/ionRefresher/
![Page 11: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/11.jpg)
hate stale docs
![Page 12: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/12.jpg)
AngularJS docs
![Page 13: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/13.jpg)
ngdoc - the tags
![Page 14: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/14.jpg)
ngdoc - the code
photo © Daniel Steger for openphoto.net)
https://github.com/angular/angular.js/blob/c086f831f/docs/src/ngdoc.js
![Page 15: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/15.jpg)
thus came dgeni(https://github.com/angular/dgeni)
project goals:● apply good design principles● configurable processors & services● using dependency injection● fully tested code-base
![Page 16: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/16.jpg)
projects using dgeni
● AngularJS
● Protractor
● Angular Material
● Ionic Framework
![Page 17: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/17.jpg)
AngularJS
https://docs.angularjs.org
● AngularJS container app● each doc is a partial HTML file● displayed by an ngInclude directive● dgeni config ~500 LOC
![Page 18: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/18.jpg)
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
![Page 19: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/19.jpg)
angular material
https://material.angularjs.org/#
● AngularJS container app● each doc is a mini Angular app● displayed in an iframe● dgeni config ~400 LOC
![Page 20: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/20.jpg)
ionic framework
http://ionicframework.com/docs/
● Jekyll hosted static app● each doc is a markdown file● dgeni config ~245 LOC
![Page 21: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/21.jpg)
● Processors - building blocks of doc generation● Services - singleton helper objects● Packages - reusable component containers
dgeni - key concepts
![Page 22: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/22.jpg)
doc processor pipeline
write files
extract tags
render content
docs
read files
docs
docs
sourcefiles
outputfiles
![Page 23: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/23.jpg)
dependency injection
Everything in dgeni is an injectable component created by a factory function:● processors● services● config blocks(similar to AngularJS)
![Page 24: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/24.jpg)
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'];});
![Page 25: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/25.jpg)
defining services
Simply export a factory function from a module:
module.exports = function log() { return function(message) { console.log(message); };};
![Page 26: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/26.jpg)
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
![Page 27: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/27.jpg)
running dgeni
var Dgeni = require('dgeni');var myPackage = require('./myPackage);var dgeni = new Dgeni([myPackage]);dgeni.generate().then(function() { ...});
![Page 28: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/28.jpg)
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)
![Page 29: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/29.jpg)
documenting your apps
![Page 30: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/30.jpg)
customize the generation
● Provide your own templates● Add extra processors● Provide a container application
![Page 31: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/31.jpg)
coding challenge
● create a new cool set of templates for the demo
https://github.com/petebacondarwin/dgeni-angular
![Page 32: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/32.jpg)
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
![Page 33: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/33.jpg)
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
![Page 34: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/34.jpg)
![Page 35: Dgeni documentation generator](https://reader033.fdocuments.us/reader033/viewer/2022061200/5476d976b4af9fae028b4625/html5/thumbnails/35.jpg)
templates (nunjucks package)
http://mozilla.github.io/nunjucks/
document
templates
renderedcontent