Skip to content
This repository was archived by the owner on Jul 29, 2024. It is now read-only.

Commit be16606

Browse files
andresjuliemr
andres
authored and
juliemr
committed
chore(dgeni): Upgrade dgeni to 0.4.0.
1 parent f4a25cb commit be16606

11 files changed

+187
-204
lines changed

‎website/docgen/dgeni-config.js

+52-72
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,12 @@
11
var _ = require('lodash');
22
var path = require('path');
3-
var packagePath = __dirname;
4-
var basePackage = require('dgeni-packages/jsdoc');
3+
var Package = require('dgeni').Package;
54

6-
module.exports = function(config) {
5+
var jsDocProcessor = require('dgeni-packages/jsdoc');
76

8-
config = basePackage(config);
9-
10-
// Use the jsdoc extractor instead of the default to parse the function name.
11-
config.set('source.extractors', [
12-
require('dgeni-packages/jsdoc/extractors/jsdoc.js')
13-
]);
14-
15-
/*
16-
* Add a couple of processors to the pipe to do extra parsing and rendering.
17-
*
18-
* tag-fixer: Get the name of the function, format the @param and @return
19-
* annotations to prepare them for rendering.
20-
* filter-jsdoc: Filter the functions that will not be part of the output
21-
* documentation and generate a unique name for the output partial file.
22-
* set-file-name: Add a file name that can be sorted alphabetically.
23-
* add-links: Add links to the source code for protractor.js, locators.js,
24-
* and webdriver.js.
25-
* add-toc: Add the table of contents.
26-
*/
27-
config.append('processing.processors', [
28-
require('./processors/tag-fixer'),
29-
require('./processors/filter-jsdoc'),
30-
require('./processors/set-file-name'),
31-
require('./processors/add-links'),
32-
require('./processors/add-toc')
33-
]);
34-
35-
/*
36-
* Add custom filters.
37-
*/
38-
config.append('rendering.filters', [
39-
require('./filters/link-slugify')
40-
]);
41-
42-
// Configure the tags that will be parsed from the jsDoc.
43-
var tagDefs = require('dgeni-packages/jsdoc/tag-defs');
7+
// Configure the tags that will be parsed from the jsDoc.
8+
jsDocProcessor.config(function(parseTagsProcessor) {
9+
var tagDefs = parseTagsProcessor.tagDefinitions;
4410

4511
// Parse the following annotations.
4612
tagDefs.push({name: 'alias'});
@@ -56,36 +22,50 @@ module.exports = function(config) {
5622
// The name tag should not be required.
5723
var nameTag = _.find(tagDefs, {name: 'name'});
5824
nameTag.required = false;
59-
60-
config.set('processing.tagDefinitions', tagDefs);
61-
62-
// OutputPath for docs that do not already have them.
63-
config.set('rendering.contentsFolder',
64-
path.resolve(config.basePath, 'build'));
65-
66-
// Base path is the protractor root dir.
67-
var basePath = path.resolve(packagePath, '../..');
68-
69-
// Generate documentation for protractor, locators, and webdriver.
70-
config.set('source.files', [
71-
{pattern: 'lib/**/protractor.js', basePath: basePath},
72-
{pattern: 'lib/**/locators.js', basePath: basePath},
73-
{pattern: 'node_modules/selenium-webdriver/lib/webdriver/webdriver.js',
74-
basePath: basePath}
75-
]);
76-
77-
// TODO(andres): Add ability to link to previous versions.
78-
config.set('linksHash', 'master');
79-
config.set('source.projectPath', basePath);
80-
config.set('rendering.outputFolder', 'build');
81-
config.set('logging.level', 'debug');
82-
83-
var docsPath = path.resolve('docgen/templates');
84-
config.set('rendering.templateFolders', [docsPath]);
85-
86-
config.set('rendering.templatePatterns', [
87-
'${ doc.template }-template.txt'
88-
]);
89-
90-
return config;
91-
};
25+
});
26+
27+
var myPackage = new Package('myPackage', [
28+
jsDocProcessor,
29+
require('dgeni-packages/nunjucks')
30+
]);
31+
32+
/*
33+
* Add a couple of processors to the pipe to do extra parsing and rendering.
34+
*
35+
* tag-fixer: Get the name of the function, format the @param and @return
36+
* annotations to prepare them for rendering.
37+
* filter-jsdoc: Filter the functions that will not be part of the output
38+
* documentation and generate a unique name for the output partial file.
39+
* add-links: Add links to the source code for protractor.js, locators.js,
40+
* and webdriver.js.
41+
* add-toc: Add the table of contents.
42+
*/
43+
myPackage.processor(require('./processors/tag-fixer'));
44+
myPackage.processor(require('./processors/filter-jsdoc'));
45+
myPackage.processor(require('./processors/set-file-name'));
46+
myPackage.processor(require('./processors/add-links'));
47+
myPackage.processor(require('./processors/add-toc'));
48+
49+
myPackage.config(function(readFilesProcessor, templateFinder, writeFilesProcessor) {
50+
51+
// Go to the protractor project root.
52+
readFilesProcessor.basePath = path.resolve(__dirname, '../..');
53+
54+
readFilesProcessor.sourceFiles = [
55+
{include: 'lib/**/protractor.js'},
56+
{include: 'lib/**/locators.js'},
57+
{include: 'node_modules/selenium-webdriver/lib/webdriver/webdriver.js'}
58+
];
59+
60+
// Add a folder to search for our own templates to use when rendering docs
61+
templateFinder.templateFolders.unshift(path.resolve('docgen/templates'));
62+
63+
// Specify how to match docs to templates.
64+
// In this case we just use the same static template for all docs
65+
templateFinder.templatePatterns.unshift('toc-template.txt');
66+
67+
// Specify where the writeFilesProcessor will write our generated doc files
68+
writeFilesProcessor.outputFolder = 'website/docgen/build';
69+
});
70+
71+
module.exports = myPackage;

‎website/docgen/filters/link-slugify.js

-8
This file was deleted.

‎website/docgen/processors/add-links.js

+29-29
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ var typeTable;
1616
/**
1717
* The hash used to generate the links to the source code.
1818
*/
19-
var linksHash;
19+
var linksHash = 'master';
2020

2121
/**
2222
* Add a link to the source code.
@@ -103,34 +103,34 @@ var getTypeString = function(param) {
103103
return escape(str);
104104
};
105105

106-
module.exports = {
107-
name: 'add-links',
108-
description: 'Add links to the external documents',
109-
runAfter: ['extracting-tags'],
110-
runBefore: ['tags-extracted'],
111-
init: function(config) {
112-
linksHash = config.linksHash;
113-
},
114-
process: function(docs) {
115-
typeTable = _.groupBy(docs, 'name');
116-
117-
docs.forEach(function(doc) {
118-
addLinkToSourceCode(doc);
119-
doc.description = addLinkToLinkAnnotation(doc.description);
120-
121-
// Add links for the param types.
122-
_.each(doc.params, function(param) {
123-
param.paramString = getTypeString(param);
106+
/**
107+
* Add links to the external documents
108+
*/
109+
module.exports = function addLinks() {
110+
return {
111+
$runAfter: ['extracting-tags'],
112+
$runBefore: ['tags-extracted'],
113+
$process: function(docs) {
114+
typeTable = _.groupBy(docs, 'name');
115+
116+
docs.forEach(function(doc) {
117+
addLinkToSourceCode(doc);
118+
doc.description = addLinkToLinkAnnotation(doc.description);
119+
120+
// Add links for the param types.
121+
_.each(doc.params, function(param) {
122+
param.paramString = getTypeString(param);
123+
});
124+
125+
// Add links for the return types.
126+
var returns = doc.returns;
127+
if (returns) {
128+
doc.returnString = getTypeString(returns);
129+
returns.description = addLinkToLinkAnnotation(returns.description);
130+
} else {
131+
doc.returnString = '';
132+
}
124133
});
125-
126-
// Add links for the return types.
127-
var returns = doc.returns;
128-
if (returns) {
129-
doc.returnString = getTypeString(returns);
130-
returns.description = addLinkToLinkAnnotation(returns.description);
131-
} else {
132-
doc.returnString = '';
133-
}
134-
});
134+
}
135135
}
136136
};

‎website/docgen/processors/add-toc.js

+37-36
Original file line numberDiff line numberDiff line change
@@ -8,43 +8,44 @@ var escapeHtml = function(htmlCode) {
88
replace(/>/g, '>');
99
};
1010

11-
module.exports = {
12-
name: 'add-toc',
13-
description: 'Add table of contents',
14-
runAfter: ['extracting-tags'],
15-
runBefore: ['tags-extracted'],
16-
init: function(config) {
17-
},
18-
process: function(docs) {
19-
// Get the properties that will be copied to the table of contents.
20-
var toc = _.map(docs, function(doc) {
21-
if (doc.view) {
22-
doc.htmlView = escapeHtml(doc.view);
23-
}
11+
/**
12+
* Add table of contents.
13+
*/
14+
module.exports = function addToc() {
15+
return {
16+
$runAfter: ['extracting-tags'],
17+
$runBefore: ['tags-extracted'],
18+
$process: function(docs) {
19+
// Get the properties that will be copied to the table of contents.
20+
var toc = _.map(docs, function(doc) {
21+
if (doc.view) {
22+
doc.htmlView = escapeHtml(doc.view);
23+
}
2424

25-
return _.pick(doc,
26-
'alias',
27-
'description',
28-
'example',
29-
'extends',
30-
'fileName',
31-
'htmlView',
32-
'name',
33-
'params',
34-
'returns',
35-
'returnString',
36-
'sourceLink',
37-
'view'
38-
);
39-
});
25+
return _.pick(doc,
26+
'alias',
27+
'description',
28+
'example',
29+
'extends',
30+
'fileName',
31+
'htmlView',
32+
'name',
33+
'params',
34+
'returns',
35+
'returnString',
36+
'sourceLink',
37+
'view'
38+
);
39+
});
4040

41-
// Replace all the docs with the table of contents.
42-
docs.length = 0;
43-
docs.push({
44-
outputPath: 'toc.json',
45-
template: 'toc',
46-
toc: toc,
47-
version: require('../../../package.json').version
48-
})
41+
// Replace all the docs with the table of contents.
42+
docs.length = 0;
43+
docs.push({
44+
outputPath: 'toc.json',
45+
template: 'toc',
46+
toc: toc,
47+
version: require('../../../package.json').version
48+
})
49+
}
4950
}
5051
};

‎website/docgen/processors/filter-jsdoc.js

+9-8
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,13 @@ var filterDocs = function(docs) {
2727
});
2828
};
2929

30-
module.exports = {
31-
name: 'filter-jsdoc',
32-
description: 'Filter functions that will not go into the documentation.',
33-
runAfter: ['extracting-tags'],
34-
runBefore: ['tags-extracted'],
35-
init: function(config) {
36-
},
37-
process: filterDocs
30+
/**
31+
* Filter functions that will not go into the documentation.
32+
*/
33+
module.exports = function filterJsDocs() {
34+
return {
35+
$runAfter: ['extracting-tags'],
36+
$runBefore: ['tags-extracted'],
37+
$process: filterDocs
38+
}
3839
};

‎website/docgen/processors/set-file-name.js

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
1-
module.exports = {
2-
name: 'set-file-name',
3-
description: 'Set the file name of the output file',
4-
runAfter: ['extracting-tags'],
5-
runBefore: ['tags-extracted'],
6-
init: function(config) {
7-
},
8-
process: function(docs) {
9-
// Generate the output file name.
10-
docs.forEach(function(doc) {
11-
doc.outputPath = doc.name + '.html';
12-
});
1+
/**
2+
* Set the input file name.
3+
*/
4+
module.exports = function setFileName() {
5+
return {
6+
$runAfter: ['extracting-tags'],
7+
$runBefore: ['tags-extracted'],
8+
$process: function(docs) {
9+
docs.forEach(function(doc) {
10+
doc.fileName = doc.fileInfo.baseName;
11+
});
1312

14-
return docs;
13+
return docs;
14+
}
1515
}
1616
};

0 commit comments

Comments
 (0)