mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2025-08-18 19:21:34 +08:00
docs in socks
This commit is contained in:
@ -1,6 +1,10 @@
|
|||||||
|
|
||||||
import {isObject, isDefined, isFunction, extend} from '../util/util';
|
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 {
|
export class IonicConfig {
|
||||||
|
|
||||||
constructor(settings) {
|
constructor(settings) {
|
||||||
@ -13,7 +17,9 @@ export class IonicConfig {
|
|||||||
extend(this._settings, settings);
|
extend(this._settings, settings);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
/**
|
||||||
|
* @description The settings description
|
||||||
|
*/
|
||||||
setting() {
|
setting() {
|
||||||
const args = arguments;
|
const args = arguments;
|
||||||
const arg0 = args[0];
|
const arg0 = args[0];
|
||||||
@ -113,6 +119,9 @@ export class IonicConfig {
|
|||||||
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The setPlatform description
|
||||||
|
*/
|
||||||
setPlatform(platform) {
|
setPlatform(platform) {
|
||||||
// get the array of active platforms, which also knows the hierarchy,
|
// get the array of active platforms, which also knows the hierarchy,
|
||||||
// with the last one the most important
|
// with the last one the most important
|
||||||
|
@ -1,5 +1,9 @@
|
|||||||
{
|
{
|
||||||
"name": "ionic2",
|
"name": "ionic2",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://github.com/driftyco/ionic2.git"
|
||||||
|
},
|
||||||
"version": "0.0.0",
|
"version": "0.0.0",
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"canonical-path": "0.0.2",
|
"canonical-path": "0.0.2",
|
||||||
@ -7,6 +11,7 @@
|
|||||||
"del": "~1.1.1",
|
"del": "~1.1.1",
|
||||||
"dgeni": "^0.4.1",
|
"dgeni": "^0.4.1",
|
||||||
"dgeni-packages": "^0.10.18",
|
"dgeni-packages": "^0.10.18",
|
||||||
|
"glob": "^5.0.14",
|
||||||
"gulp": "~3.8.10",
|
"gulp": "~3.8.10",
|
||||||
"gulp-autoprefixer": "^2.3.0",
|
"gulp-autoprefixer": "^2.3.0",
|
||||||
"gulp-babel": "^5.1.0",
|
"gulp-babel": "^5.1.0",
|
||||||
|
@ -2,20 +2,27 @@ var Package = require('dgeni').Package;
|
|||||||
var jsdocPackage = require('dgeni-packages/jsdoc');
|
var jsdocPackage = require('dgeni-packages/jsdoc');
|
||||||
var nunjucksPackage = require('dgeni-packages/nunjucks');
|
var nunjucksPackage = require('dgeni-packages/nunjucks');
|
||||||
var typescriptPackage = require('./typescript-package');
|
var typescriptPackage = require('./typescript-package');
|
||||||
|
var linksPackage = require('./links-package');
|
||||||
|
var gitPackage = require('dgeni-packages/git');
|
||||||
var path = require('path');
|
var path = require('path');
|
||||||
|
|
||||||
// Define the dgeni package for generating the docs
|
// 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) {
|
.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
|
// Don't run unwanted processors
|
||||||
readFilesProcessor.$enabled = false; // We are not using the normal file reading processor
|
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$/;
|
// jsdocFileReader.defaultPattern = /\.(j|t)s$/;
|
||||||
// readFilesProcessor.fileReaders = [jsdocFileReader];
|
// readFilesProcessor.fileReaders = [jsdocFileReader];
|
||||||
@ -27,6 +34,72 @@ module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, ty
|
|||||||
readTypeScriptModules.sourceFiles = [
|
readTypeScriptModules.sourceFiles = [
|
||||||
'ionic/ionic.ts'
|
'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'
|
||||||
|
// });
|
||||||
|
// });
|
||||||
|
13
scripts/docs/links-package/index.js
Normal file
13
scripts/docs/links-package/index.js
Normal file
@ -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);
|
||||||
|
});
|
33
scripts/docs/links-package/inline-tag-defs/link.js
Normal file
33
scripts/docs/links-package/inline-tag-defs/link.js
Normal file
@ -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 "<a href='" + linkInfo.url + "'>" + linkInfo.title + "</a>";
|
||||||
|
});
|
||||||
|
}
|
||||||
|
};
|
||||||
|
};
|
72
scripts/docs/links-package/services/getLinkInfo.js
Normal file
72
scripts/docs/links-package/services/getLinkInfo.js
Normal file
@ -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;
|
||||||
|
};
|
||||||
|
};
|
51
scripts/docs/templates/common.template.html
vendored
Normal file
51
scripts/docs/templates/common.template.html
vendored
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
{% macro paramList(params) -%}
|
||||||
|
{%- if params -%}<span class="params">(
|
||||||
|
{%- for param in params -%}
|
||||||
|
<span class="param">{$ param | escape $}{% if not loop.last %}, {% endif %}</span>
|
||||||
|
{%- endfor %})</span>
|
||||||
|
{%- endif %}
|
||||||
|
{%- endmacro -%}
|
||||||
|
{% macro githubViewLink(doc) -%}
|
||||||
|
<a href="https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/master/{$ doc.fileInfo.relativePath $}#L{$ doc.location.start.line+1 $}-L{$ doc.location.end.line+1 $}">{$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $})</a>
|
||||||
|
{%- endmacro -%}
|
||||||
|
|
||||||
|
{% block body %}
|
||||||
|
<h1 class="class export">{$ doc.name $} <span class="type">{$ doc.docType $}</span></h1>
|
||||||
|
<p class="module">exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }<br/>
|
||||||
|
defined in {$ githubViewLink(doc) $}
|
||||||
|
</p>
|
||||||
|
<p>{$ doc.description | marked $}</p>
|
||||||
|
|
||||||
|
{%- if doc.decorators %}
|
||||||
|
<h2>Annotations</h2>
|
||||||
|
{%- for decorator in doc.decorators %}
|
||||||
|
<h3 class="annotation">@{$ decorator.name $}{$ paramList(decorator.arguments) $}</h3>
|
||||||
|
{% endfor %}
|
||||||
|
{% endif -%}
|
||||||
|
|
||||||
|
{%- if doc.constructorDoc or doc.members.length -%}
|
||||||
|
<h2>Members</h2>
|
||||||
|
|
||||||
|
{%- if doc.constructorDoc %}
|
||||||
|
<section class="member constructor">
|
||||||
|
<h1 id="constructor" class="name">{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) $}</h1>
|
||||||
|
{% marked %}
|
||||||
|
{$ doc.constructorDoc.description $}
|
||||||
|
{% endmarked %}
|
||||||
|
</section>
|
||||||
|
{% endif -%}
|
||||||
|
|
||||||
|
{%- for member in doc.members %}{% if not member.private %}
|
||||||
|
<section class="member">
|
||||||
|
<h1 id="{$ member.name $}" class="name">
|
||||||
|
{$ member.name $}{% if member.optional %}?{% endif %}{$ paramList(member.params) $}
|
||||||
|
</h1>
|
||||||
|
{% marked %}
|
||||||
|
{$ member.description $}
|
||||||
|
{% endmarked %}
|
||||||
|
</section>
|
||||||
|
|
||||||
|
{% endif %}{% endfor %}
|
||||||
|
{%- endif -%}
|
||||||
|
|
||||||
|
{% endblock %}
|
100
scripts/docs/typescript-definition-package/index.js
Normal file
100
scripts/docs/typescript-definition-package/index.js
Normal file
@ -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'
|
||||||
|
];
|
||||||
|
});
|
@ -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 {}; });
|
||||||
|
|
||||||
|
};
|
@ -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;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
};
|
||||||
|
};
|
@ -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');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
});
|
@ -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 <https://github.com/angular/>
|
||||||
|
// 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;
|
||||||
|
}
|
@ -1,4 +1,4 @@
|
|||||||
require('../../tools/transpiler/index.js').init();
|
//require('../../tools/transpiler/index.js').init();
|
||||||
|
|
||||||
var basePackage = require('dgeni-packages/base');
|
var basePackage = require('dgeni-packages/base');
|
||||||
var Package = require('dgeni').Package;
|
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
|
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({
|
computePathsProcessor.pathTemplates.push({
|
||||||
docTypes: ['module'],
|
docTypes: ['module'],
|
||||||
|
Reference in New Issue
Block a user