diff --git a/ionic/config/config.ts b/ionic/config/config.ts index 6bd799c01e..7cb6b0d62b 100644 --- a/ionic/config/config.ts +++ b/ionic/config/config.ts @@ -1,6 +1,10 @@ + import {isObject, isDefined, isFunction, extend} from '../util/util'; - +/** +* This is the Ionic Config +* @usage this is what you do to use it +*/ export class IonicConfig { constructor(settings) { @@ -13,7 +17,9 @@ export class IonicConfig { extend(this._settings, settings); } } - + /** + * @description The settings description + */ setting() { const args = arguments; const arg0 = args[0]; @@ -113,6 +119,9 @@ export class IonicConfig { } + /** + * The setPlatform description + */ setPlatform(platform) { // get the array of active platforms, which also knows the hierarchy, // with the last one the most important diff --git a/package.json b/package.json index 631752ceb6..e07d9c6106 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,9 @@ { "name": "ionic2", + "repository": { + "type": "git", + "url": "https://github.com/driftyco/ionic2.git" + }, "version": "0.0.0", "devDependencies": { "canonical-path": "0.0.2", @@ -7,6 +11,7 @@ "del": "~1.1.1", "dgeni": "^0.4.1", "dgeni-packages": "^0.10.18", + "glob": "^5.0.14", "gulp": "~3.8.10", "gulp-autoprefixer": "^2.3.0", "gulp-babel": "^5.1.0", diff --git a/scripts/docs/dgeni-config.js b/scripts/docs/dgeni-config.js index ff80b96d72..dc9b1c1ed6 100644 --- a/scripts/docs/dgeni-config.js +++ b/scripts/docs/dgeni-config.js @@ -2,20 +2,27 @@ var Package = require('dgeni').Package; var jsdocPackage = require('dgeni-packages/jsdoc'); var nunjucksPackage = require('dgeni-packages/nunjucks'); var typescriptPackage = require('./typescript-package'); +var linksPackage = require('./links-package'); +var gitPackage = require('dgeni-packages/git'); var path = require('path'); // Define the dgeni package for generating the docs -module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage/*, linksPackage, gitPackage*/]) +module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, gitPackage]) .config(function(log) { - log.level = 'debug' //'warn'; + log.level = 'silly' //'warn'; }) -.config(function(readFilesProcessor, inlineTagProcessor, readTypeScriptModules, createTypeDefinitionFile) { +.config(function(renderDocsProcessor, versionInfo) { + renderDocsProcessor.extraData.versionInfo = versionInfo; +}) + +//configure file reading +.config(function(readFilesProcessor, inlineTagProcessor, readTypeScriptModules) { // Don't run unwanted processors readFilesProcessor.$enabled = false; // We are not using the normal file reading processor - inlineTagProcessor.$enabled = false; // We are not actually processing the inline link tags + // inlineTagProcessor.$enabled = false; // We are not actually processing the inline link tags // jsdocFileReader.defaultPattern = /\.(j|t)s$/; // readFilesProcessor.fileReaders = [jsdocFileReader]; @@ -27,6 +34,72 @@ module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, ty readTypeScriptModules.sourceFiles = [ 'ionic/ionic.ts' ]; + readTypeScriptModules.hidePrivateMembers = true; +}) - writeFilesProcessor.outputFolder = 'dist/docs' -}); +.config(function(parseTagsProcessor) { + // We actually don't want to parse param docs in this package as we are getting the data out using TS + parseTagsProcessor.tagDefinitions.forEach(function(tagDef) { + if (tagDef.name === 'param') { + tagDef.docProperty = 'paramData'; + tagDef.transforms = []; + } + }); +}) + +// Configure links +.config(function(getLinkInfo) { + getLinkInfo.useFirstAmbiguousLink = false; +}) + +// Configure file writing +.config(function(writeFilesProcessor) { + writeFilesProcessor.outputFolder = 'dist/docs'; +}) + +// Configure rendering +.config(function(templateFinder, templateEngine) { + + // Nunjucks and Angular conflict in their template bindings so change the Nunjucks + templateEngine.config.tags = { + variableStart: '{$', + variableEnd: '$}' + }; + + templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates')); + + // Specify how to match docs to templates. + // In this case we just use the same static template for all docs + templateFinder.templatePatterns.unshift('common.template.html'); + + // templateFinder.templatePatterns = [ + // '${ doc.template }', + // '${ doc.id }.${ doc.docType }.template.html', + // '${ doc.id }.template.html', + // '${ doc.docType }.template.html', + // 'common.template.html' + // ]; +}) + +// Configure ids and paths +// .config(function(computeIdsProcessor, computePathsProcessor) { +// computeIdsProcessor.idTemplates.push({ +// docTypes: ['guide'], +// getId: function(doc) { +// return doc.fileInfo.relativePath +// // path should be relative to `modules` folder +// .replace(/.*\/?modules\//, '') +// // path should not include `/docs/` +// .replace(/\/docs\//, '/') +// // path should not have a suffix +// .replace(/\.\w*$/, ''); +// }, +// getAliases: function(doc) { return [doc.id]; } +// }); +// +// computePathsProcessor.pathTemplates.push({ +// docTypes: ['guide'], +// pathTemplate: '/${id}', +// outputPathTemplate: 'partials/guides/${id}.html' +// }); +// }); diff --git a/scripts/docs/links-package/index.js b/scripts/docs/links-package/index.js new file mode 100644 index 0000000000..f1270912df --- /dev/null +++ b/scripts/docs/links-package/index.js @@ -0,0 +1,13 @@ +var Package = require('dgeni').Package; + +module.exports = new Package('links', []) + +.factory(require('./inline-tag-defs/link')) +.factory(require('dgeni-packages/ngdoc/services/getAliases')) +.factory(require('dgeni-packages/ngdoc/services/getDocFromAlias')) +.factory(require('./services/getLinkInfo')) + +.config(function(inlineTagProcessor, linkInlineTagDef) { + debugger; + inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef); +}); diff --git a/scripts/docs/links-package/inline-tag-defs/link.js b/scripts/docs/links-package/inline-tag-defs/link.js new file mode 100644 index 0000000000..89272c63ca --- /dev/null +++ b/scripts/docs/links-package/inline-tag-defs/link.js @@ -0,0 +1,33 @@ +var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/; + +/** + * @dgService linkInlineTagDef + * @description + * Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors + * @kind function + * @param {Object} url The url to match + * @param {Function} docs error message + * @return {String} The html link information + * + * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc + */ +module.exports = function linkInlineTagDef(getLinkInfo, createDocMessage, log) { + return { + name: 'link', + description: 'Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors', + handler: function(doc, tagName, tagDescription) { + + // Parse out the uri and title + return tagDescription.replace(INLINE_LINK, function(match, uri, title) { + + var linkInfo = getLinkInfo(uri, title, doc); + + if ( !linkInfo.valid ) { + log.warn(createDocMessage(linkInfo.error, doc)); + } + + return "" + linkInfo.title + ""; + }); + } + }; +}; \ No newline at end of file diff --git a/scripts/docs/links-package/services/getLinkInfo.js b/scripts/docs/links-package/services/getLinkInfo.js new file mode 100644 index 0000000000..787ff04338 --- /dev/null +++ b/scripts/docs/links-package/services/getLinkInfo.js @@ -0,0 +1,72 @@ +var _ = require('lodash'); +var path = require('canonical-path'); + +/** + * @dgService getLinkInfo + * @description + * Get link information to a document that matches the given url + * @kind function + * @param {String} url The url to match + * @param {String} title An optional title to return in the link information + * @return {Object} The link information + * + * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc + */ +module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) { + + return function getLinkInfoImpl(url, title, currentDoc) { + var linkInfo = { + url: url, + type: 'url', + valid: true, + title: title || url + }; + + if ( !url ) { + throw new Error('Invalid url'); + } + + var docs = getDocFromAlias(url, currentDoc); + + if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 ) { + + linkInfo.valid = false; + linkInfo.errorType = 'ambiguous'; + linkInfo.error = 'Ambiguous link: "' + url + '".\n' + + docs.reduce(function(msg, doc) { return msg + '\n "' + doc.id + '" ('+ doc.docType + ') : (' + doc.path + ' / ' + doc.fileInfo.relativePath + ')'; }, 'Matching docs: '); + + } else if ( docs.length >= 1 ) { + + linkInfo.url = docs[0].path; + linkInfo.title = title || encodeCodeBlock(docs[0].name, true); + linkInfo.type = 'doc'; + + if ( getLinkInfoImpl.relativeLinks && currentDoc && currentDoc.path ) { + var currentFolder = path.dirname(currentDoc.path); + var docFolder = path.dirname(linkInfo.url); + var relativeFolder = path.relative(path.join('/', currentFolder), path.join('/', docFolder)); + linkInfo.url = path.join(relativeFolder, path.basename(linkInfo.url)); + log.debug(currentDoc.path, docs[0].path, linkInfo.url); + } + + } else if ( url.indexOf('#') > 0 ) { + var pathAndHash = url.split('#'); + linkInfo = getLinkInfoImpl(pathAndHash[0], title, currentDoc); + linkInfo.url = linkInfo.url + '#' + pathAndHash[1]; + return linkInfo; + + } else if ( url.indexOf('/') === -1 && url.indexOf('#') !== 0 ) { + + linkInfo.valid = false; + linkInfo.errorType = 'missing'; + linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"'; + + } else { + + linkInfo.title = title || (( url.indexOf('#') === 0 ) ? url.substring(1) : path.basename(url, '.html')); + + } + + return linkInfo; + }; +}; \ No newline at end of file diff --git a/scripts/docs/templates/common.template.html b/scripts/docs/templates/common.template.html new file mode 100644 index 0000000000..3c58715f16 --- /dev/null +++ b/scripts/docs/templates/common.template.html @@ -0,0 +1,51 @@ +{% macro paramList(params) -%} + {%- if params -%}( + {%- for param in params -%} + {$ param | escape $}{% if not loop.last %}, {% endif %} + {%- endfor %}) + {%- endif %} +{%- endmacro -%} +{% macro githubViewLink(doc) -%} + {$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $}) +{%- endmacro -%} + +{% block body %} +

{$ doc.name $} {$ doc.docType $}

+

exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }
+defined in {$ githubViewLink(doc) $} +

+

{$ doc.description | marked $}

+ +{%- if doc.decorators %} +

Annotations

+{%- for decorator in doc.decorators %} +

@{$ decorator.name $}{$ paramList(decorator.arguments) $}

+{% endfor %} +{% endif -%} + +{%- if doc.constructorDoc or doc.members.length -%} +

Members

+ +{%- if doc.constructorDoc %} +
+

{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) $}

+ {% marked %} + {$ doc.constructorDoc.description $} + {% endmarked %} +
+{% endif -%} + +{%- for member in doc.members %}{% if not member.private %} +
+

+ {$ member.name $}{% if member.optional %}?{% endif %}{$ paramList(member.params) $} +

+ {% marked %} + {$ member.description $} + {% endmarked %} +
+ +{% endif %}{% endfor %} +{%- endif -%} + +{% endblock %} diff --git a/scripts/docs/typescript-definition-package/index.js b/scripts/docs/typescript-definition-package/index.js new file mode 100644 index 0000000000..532cfe5d3d --- /dev/null +++ b/scripts/docs/typescript-definition-package/index.js @@ -0,0 +1,100 @@ +var Package = require('dgeni').Package; +var jsdocPackage = require('dgeni-packages/jsdoc'); +var nunjucksPackage = require('dgeni-packages/nunjucks'); +var typescriptPackage = require('../typescript-package'); +var gitPackage = require('dgeni-packages/git'); +var path = require('canonical-path'); + +// Define the dgeni package for generating the docs +module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, gitPackage]) + +// Register the processors +.processor(require('./processors/createTypeDefinitionFile')) + +.config(function(readFilesProcessor, inlineTagProcessor) { + readFilesProcessor.basePath = path.resolve(__dirname, '../..'); + // Don't run unwanted processors + readFilesProcessor.$enabled = false; + inlineTagProcessor.$enabled = false; +}) + + +// Configure the log service +.config(function(log) { + log.level = 'info'; +}) + + +.config(function(renderDocsProcessor, versionInfo) { + renderDocsProcessor.extraData.versionInfo = versionInfo; +}) + +.config(function(readFilesProcessor, inlineTagProcessor, readTypeScriptModules, createTypeDefinitionFile) { + + // Don't run unwanted processors + readFilesProcessor.$enabled = false; // We are not using the normal file reading processor + inlineTagProcessor.$enabled = false; // We are not actually processing the inline link tags + + // Configure file reading + readFilesProcessor.basePath = path.resolve(__dirname, '../..'); + readTypeScriptModules.sourceFiles = [ + 'angular2/angular2.ts', + 'angular2/router.ts' + ]; + readTypeScriptModules.basePath = path.resolve(path.resolve(__dirname, '../../modules')); + + createTypeDefinitionFile.typeDefinitions = [ + { + id: 'angular2/angular2', + modules: { + 'angular2/angular2': 'angular2/angular2', + } + }, + { + id: 'angular2/router', + modules: { + 'angular2/router': 'angular2/router' + } + } + ]; +}) + + +.config(function(parseTagsProcessor, getInjectables) { + // We actually don't want to parse param docs in this package as we are getting the data out using TS + parseTagsProcessor.tagDefinitions.forEach(function(tagDef) { + if (tagDef.name === 'param') { + tagDef.docProperty = 'paramData'; + tagDef.transforms = []; + } + }); + +}) + + +// Configure file writing +.config(function(writeFilesProcessor) { + writeFilesProcessor.outputFolder = 'dist/docs'; +}) + + +// Configure rendering +.config(function(templateFinder, templateEngine) { + + // Nunjucks and Angular conflict in their template bindings so change Nunjucks + templateEngine.config.tags = { + variableStart: '{$', + variableEnd: '$}' + }; + + templateFinder.templateFolders + .unshift(path.resolve(__dirname, 'templates')); + + templateFinder.templatePatterns = [ + '${ doc.template }', + '${ doc.id }.${ doc.docType }.template.html', + '${ doc.id }.template.html', + '${ doc.docType }.template.html', + 'common.template.html' + ]; +}); \ No newline at end of file diff --git a/scripts/docs/typescript-definition-package/mocks/mockPackage.js b/scripts/docs/typescript-definition-package/mocks/mockPackage.js new file mode 100644 index 0000000000..6923091000 --- /dev/null +++ b/scripts/docs/typescript-definition-package/mocks/mockPackage.js @@ -0,0 +1,11 @@ +var Package = require('dgeni').Package; + +module.exports = function mockPackage() { + + return new Package('mockPackage', [require('../')]) + + // provide a mock log service + .factory('log', function() { return require('dgeni/lib/mocks/log')(false); }) +// .factory('templateEngine', function() { return {}; }); + +}; diff --git a/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.js b/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.js new file mode 100644 index 0000000000..f3bc002caa --- /dev/null +++ b/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.js @@ -0,0 +1,86 @@ +var _ = require('lodash'); +var path = require('canonical-path'); + +module.exports = function createTypeDefinitionFile(log) { + + return { + $runAfter: ['processing-docs'], + $runBefore: ['docs-processed'], + $validate: { + dtsPath: { presence: true }, + dtsExtension: { presence: true }, + typeDefinitions: { presence: true } + }, + dtsPath: 'typings', + dtsExtension: '.d.ts', + typeDefinitions: [], + $process: function(docs) { + var dtsPath = this.dtsPath; + var dtsExtension = this.dtsExtension; + + // For each type definition that we wish to create we define a dgeni "doc" for it + var typeDefDocs = _.map(this.typeDefinitions, function(def) { + + var id = def.id + dtsExtension; + var docPath = path.join(dtsPath, id); + + return { + docType: 'type-definition', + id: id, + aliases: [id], + path: docPath, + outputPath: docPath, + // A type definition may include a number of top level modules + // And those modules could be aliased (such as 'angular2/angular2.api' -> 'angular2/angular2') + moduleDocs: _.transform(def.modules, function(moduleDocs, id, alias) { + moduleDocs[id] = { id: alias, doc: null }; + }) + }; + }); + + // Now add all the module docs to their corresponding type definition doc + _.forEach(docs, function(doc) { + _.forEach(typeDefDocs, function(typeDefDoc) { + if(typeDefDoc.moduleDocs[doc.id]) { + // Add a copy, because we are going to modify it + typeDefDoc.moduleDocs[doc.id].doc = doc; + } + }); + }); + + return _.filter(typeDefDocs, function(doc) { + _.forEach(doc.moduleDocs, function(modDoc, alias) { + if (!doc || !modDoc.doc) { + log.error('createTypeDefinitionFile processor: no such module "' + alias + '" (Did you forget to add it to the modules to load?)'); + doc = null; + return; + } + _.forEach(modDoc.doc.exports, function(exportDoc) { + + // Search for classes with a constructor marked as `@private` + if (exportDoc.docType === 'class' && exportDoc.constructorDoc && exportDoc.constructorDoc.private) { + + // Convert this class to an interface with no constructor + exportDoc.docType = 'interface'; + exportDoc.constructorDoc = null; + + if (exportDoc.heritage) { + // convert the heritage since interfaces use `extends` not `implements` + exportDoc.heritage = exportDoc.heritage.replace('implements', 'extends'); + } + + // Add the `declare var SomeClass extends InjectableReference` construct + modDoc.doc.exports.push({ + docType: 'var', + name: exportDoc.name, + id: exportDoc.id, + heritage: ': InjectableReference' + }); + } + }); + }); + return !!doc; + }); + } + }; +}; diff --git a/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.spec.js b/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.spec.js new file mode 100644 index 0000000000..1bf15092d5 --- /dev/null +++ b/scripts/docs/typescript-definition-package/processors/createTypeDefinitionFile.spec.js @@ -0,0 +1,48 @@ +var mockPackage = require('../mocks/mockPackage'); +var Dgeni = require('dgeni'); +var path = require('canonical-path'); +var _ = require('lodash'); + +describe('createTypeDefinitionFile processor', function() { + var dgeni, injector, processor; + + beforeEach(function() { + dgeni = new Dgeni([mockPackage()]); + injector = dgeni.configureInjector(); + processor = injector.get('createTypeDefinitionFile'); + + // Initialize the processor + processor.typeDefinitions = [{ + id: 'angular2/angular2', + modules: { 'angular2/angular2': 'angular2/angular2' } + }]; + }); + + + + describe('classes with private constructors', function() { + + it('should convert heritage from `implements` into `extends`', function() { + + // Create some mock docs for testing + var docs = [ + { + id: 'angular2/angular2', + exports: [ + { docType: 'class', heritage: 'implements Xyz', constructorDoc: { private: true } } + ] + } + ]; + + docs = processor.$process(docs); + + expect(docs.length).toEqual(1); + expect(docs[0].docType).toEqual('type-definition'); + + var moduleDoc = docs[0].moduleDocs['angular2/angular2'].doc; + expect(moduleDoc.exports.length).toEqual(2); + expect(moduleDoc.exports[0].heritage).toEqual('extends Xyz'); + }); + }); + +}); \ No newline at end of file diff --git a/scripts/docs/typescript-definition-package/templates/type-definition.template.html b/scripts/docs/typescript-definition-package/templates/type-definition.template.html new file mode 100644 index 0000000000..4ebceffaa0 --- /dev/null +++ b/scripts/docs/typescript-definition-package/templates/type-definition.template.html @@ -0,0 +1,72 @@ + +{%- macro commentBlock(doc, level) -%} +{%- if doc.content | trim %} + +{% if level > 1 %}{$ '/**' | indent(level-1, true) | replace(r/\n$/, "") $}{% else %}/**{% endif %} +{$ doc.content | trim | replace(r/^/gm, "* ") | indent(level, true) | replace(r/\n$/, "") $} +{$ '*/' | indent(level, true) | replace(r/\n$/, "") $}{% endif -%} +{%- endmacro -%} + + +{%- macro memberInfo(member) -%} +{$ commentBlock(member, 5) $} + {$ member.name $}{% if member.optional %}?{% endif -%} +{% if member.typeParameters %}<{% for typeParam in member.typeParameters %}{$ typeParam $}{% if not loop.last %}, {% endif %}{% endfor %}>{% endif -%} +{%- if member.parameters -%}({% for param in member.parameters %}{$ param $}{% if not loop.last %}, {% endif %}{% endfor %}){%- endif -%} +{%- if member.returnType == 'Directive' %}: DirectiveAnnotation{%- elif member.returnType -%}: {$ member.returnType $}{%- else -%}: void +{%- endif -%}; +{%- endmacro -%} + + +// Type definitions for Angular v{$ versionInfo.currentVersion.full | replace(r/\+/, "_") $} +// Project: http://angular.io/ +// Definitions by: angular team +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +// *********************************************************** +// This file is generated by the Angular build process. +// Please do not create manual edits or send pull requests +// modifying this file. +// *********************************************************** +{% block staticDeclarations %}{% endblock %} +{% for alias, module in doc.moduleDocs %} +{$ commentBlock(module.doc, 1) $} +declare module ng { + + {%- for export in module.doc.exports -%} + {%- if export.content -%} + {$ commentBlock(export, 3) $} + {%- endif %} + {$ export.docType $} {$ export.name $}{$ export.typeParams $}{%- if export.heritage == ' extends Directive' %} extends DirectiveAnnotation{% else %}{$ export.heritage $}{% endif %} + {%- if export.docType == 'class' or export.docType == 'interface' %} { + {%- if export.newMember %} + {$ memberInfo(export.newMember) $} + {% endif %} + {%- if export.callMember %} + {$ memberInfo(export.callMember) $} + {% endif -%} + {%- for member in export.members %} + {$ memberInfo(member) $} + {%- endfor %} + } + + {%- elif export.docType == 'enum' %} { + {%- for member in export.members %} + {$ member $}{% if not loop.last %}, + {%- endif -%} + {%- endfor %} + } + + {%- else -%} + {% if export.parameters %}({% for param in export.parameters %}{$ param $}{% if not loop.last %}, {% endif %}{% endfor %}){%- endif %} + {%- if export.returnType %} : {$ export.returnType $} {% endif -%} + ; + {%- endif %} + {% endfor %} +} + +{% endfor %} + +declare module "angular2/angular2" { + export = ng; +} diff --git a/scripts/docs/typescript-package/index.js b/scripts/docs/typescript-package/index.js index 165c654640..a813918daa 100644 --- a/scripts/docs/typescript-package/index.js +++ b/scripts/docs/typescript-package/index.js @@ -1,4 +1,4 @@ -require('../../tools/transpiler/index.js').init(); +//require('../../tools/transpiler/index.js').init(); var basePackage = require('dgeni-packages/base'); var Package = require('dgeni').Package; @@ -53,7 +53,7 @@ module.exports = new Package('typescript-parsing', [basePackage]) getOutputPath: function() {} // These docs are not written to their own file, instead they are part of their class doc }); - var MODULES_DOCS_PATH = 'partials/modules'; + var MODULES_DOCS_PATH = 'docs'; computePathsProcessor.pathTemplates.push({ docTypes: ['module'],