iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: Dart API doc gen cleanup and refactoring (#2641) 

- gulp task: don’t copy over internal libraries.
- Adjust anchor hrefs rather than use `<base href>` in generated API
pages. The net effect is the same.
This commit is contained in:
Patrice Chalin 2016-10-20 14:29:08 -07:00 committed by Filipe Silva
parent 870ce124d2
commit 75f37b76eb
2 changed files with 19 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
gulpfile.js
View File

@ -1381,14 +1381,14 @@ function buildApiDocsForDart() {
dabInfo.ngDartDocPath = path.join(ngPathFor('dart'), relDartDocApiDir); dabInfo.ngDartDocPath = path.join(ngPathFor('dart'), relDartDocApiDir);
// Exclude API entries for developer/internal libraries. Also exclude entries for // Exclude API entries for developer/internal libraries. Also exclude entries for
// the top-level catch all "angular2" library (otherwise every entry appears twice). // the top-level catch all "angular2" library (otherwise every entry appears twice).
dabInfo.excludeLibRegExp = new RegExp(/^(?!angular2)|\.testing|_|codegen|^angular2$/); dabInfo.excludeLibRegExp = new RegExp(/^(?!angular2)|testing|_|codegen|^angular2$/);
try { try {
checkAngularProjectPath(ngPathFor('dart')); checkAngularProjectPath(ngPathFor('dart'));
var destPath = dabInfo.ngIoDartApiDocPath; var destPath = dabInfo.ngIoDartApiDocPath;
var sourceDirs = fs.readdirSync(dabInfo.ngDartDocPath) var sourceDirs = fs.readdirSync(dabInfo.ngDartDocPath)
.filter((name) => !name.match(/^index/)) .filter(name => !name.match(/^index|^(?!angular2)|testing|codegen/))
.map((name) => path.join(dabInfo.ngDartDocPath, name)); .map(name => path.join(dabInfo.ngDartDocPath, name));
log.info(`Building Dart API pages for ${sourceDirs.length} libraries`); log.info(`Building Dart API pages for ${sourceDirs.length} libraries`);
return copyFiles(sourceDirs, [destPath]).then(() => { return copyFiles(sourceDirs, [destPath]).then(() => {
@ -1398,7 +1398,6 @@ function buildApiDocsForDart() {
const tmpDocsPath = path.resolve(path.join(process.env.HOME, 'tmp/docs.json')); const tmpDocsPath = path.resolve(path.join(process.env.HOME, 'tmp/docs.json'));
if (argv.dumpDocsJson) fs.writeFileSync(tmpDocsPath, JSON.stringify(apiEntries, null, 2)); if (argv.dumpDocsJson) fs.writeFileSync(tmpDocsPath, JSON.stringify(apiEntries, null, 2));
dab.createApiDataAndJadeFiles(apiEntries); dab.createApiDataAndJadeFiles(apiEntries);
}).catch((err) => { }).catch((err) => {
console.error(err); console.error(err);
}); });

20
tools/dart-api-builder/dab.js
View File

@ -135,7 +135,7 @@ module.exports = function dabFactory(ngIoProjPath) {
assert(depth === 1 || depth == 2, 'depth ' + depth); assert(depth === 1 || depth == 2, 'depth ' + depth);
const jadeFilePath = path.resolve(outFileNoExtn + '.jade'); const jadeFilePath = path.resolve(outFileNoExtn + '.jade');
const breadcrumbs = $('header > nav ol.breadcrumbs'); const breadcrumbs = $('header > nav ol.breadcrumbs');
fs.writeFileSync(jadeFilePath, apiEntryJadeTemplate(depth, breadcrumbs, div)); fs.writeFileSync(jadeFilePath, apiEntryJadeTemplate($, depth, breadcrumbs, div));
// In case harp cached the .html version, remove it since it will be generated. // In case harp cached the .html version, remove it since it will be generated.
try { try {
fs.unlinkSync(path.resolve(outFileNoExtn + '.html')); fs.unlinkSync(path.resolve(outFileNoExtn + '.html'));
@ -197,6 +197,16 @@ module.exports = function dabFactory(ngIoProjPath) {
return _self; return _self;
}; };
function _adjustAnchorHref($, $elt, hrefPathPrefix) {
if (!hrefPathPrefix) return;
$elt.find('a[href]').each((i, e) => {
let href = $(e).attr('href')
// Do nothing to absolute or external links
if (href.match(/^\/|^[a-z]+:/)) return;
$(e).attr('href', `${hrefPathPrefix}/${href}`);
});
}
function _indentedEltHtml($elt, i, filterFnOpt) { function _indentedEltHtml($elt, i, filterFnOpt) {
let lines = $elt.html().split('\n'); let lines = $elt.html().split('\n');
if (filterFnOpt) lines = lines.filter(filterFnOpt); if (filterFnOpt) lines = lines.filter(filterFnOpt);
@ -204,10 +214,12 @@ function _indentedEltHtml($elt, i, filterFnOpt) {
return lines.map((line) => `${indent}| ${line}`).join('\n'); return lines.map((line) => `${indent}| ${line}`).join('\n');
} }
function apiEntryJadeTemplate(baseHrefDepth, $breadcrumbs, $mainDiv) { function apiEntryJadeTemplate($, baseHrefDepth, $breadcrumbs, $mainDiv) {
const baseHref = path.join(...Array(baseHrefDepth).fill('..')); const baseHref = path.join(...Array(baseHrefDepth).fill('..'));
// TODO/investigate: for some reason $breadcrumbs.html() is missing the <ol></ol>. We add it back in the template below. // TODO/investigate: for some reason $breadcrumbs.html() is missing the <ol></ol>. We add it back in the template below.
_adjustAnchorHref($, $breadcrumbs, baseHref);
const breadcrumbs = _indentedEltHtml($breadcrumbs, 6, (line) => !line.match(/^\s*$/)); const breadcrumbs = _indentedEltHtml($breadcrumbs, 6, (line) => !line.match(/^\s*$/));
_adjustAnchorHref($, $mainDiv, baseHref);
const mainDivHtml = _indentedEltHtml($mainDiv, 4); const mainDivHtml = _indentedEltHtml($mainDiv, 4);
// WARNING: since the following is Jade, indentation is significant. // WARNING: since the following is Jade, indentation is significant.
const result = ` const result = `
@ -217,8 +229,8 @@ include ${baseHref}/../_util-fns
block head-extra block head-extra
// generated Dart API page template: head-extra // generated Dart API page template: head-extra
//- <base> is required because all the links in dartdoc generated pages are "pseudo-absolute" //- <base> is no longer required
base(href="${baseHref}") //- base(href="${baseHref}")
block breadcrumbs block breadcrumbs
// generated Dart API page template: breadcrumbs // generated Dart API page template: breadcrumbs