Skip to content

Commit 2a7febe

Browse files
alexwolfepetebacondarwin
alexwolfe
authored and
petebacondarwin
committed
chore(doc-gen): generate docs for angular.io
You can generate docs for comsumption by the angular.io website by running: ```bash gulp docs/angular.io ``` The generated docs can be found in `dist/angular.io`
1 parent b72eb07 commit 2a7febe

File tree

15 files changed

+389
-2
lines changed

15 files changed

+389
-2
lines changed

‎docs/angular.io-package/index.js‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
var path = require('canonical-path');
2+
var Package = require('dgeni').Package;
3+
var basePackage = require('../public-docs-package');
4+
5+
var PARTIAL_PATH = 'partials';
6+
var MODULES_DOCS_PATH = PARTIAL_PATH + '/api';
7+
8+
module.exports = new Package('angular.io', [basePackage])
9+
10+
.factory(require('./services/renderMarkdown'))
11+
.processor(require('./processors/addJadeDataDocsProcessor'))
12+
13+
// Configure rendering
14+
.config(function(templateFinder, templateEngine) {
15+
16+
templateFinder.templateFolders
17+
.unshift(path.resolve(__dirname, 'templates'));
18+
})
19+
20+
.config(function(writeFilesProcessor) {
21+
writeFilesProcessor.outputFolder = 'dist/angular.io';
22+
})
23+
24+
25+
.config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {
26+
27+
computePathsProcessor.pathTemplates.push({
28+
docTypes: ['module'],
29+
pathTemplate: '${id}.html',
30+
outputPathTemplate: MODULES_DOCS_PATH + '/${id}/index.jade'
31+
});
32+
33+
computePathsProcessor.pathTemplates.push({
34+
docTypes: EXPORT_DOC_TYPES,
35+
pathTemplate: '${moduleDoc.id}/${name}-${docType}.html',
36+
outputPathTemplate: MODULES_DOCS_PATH + '/${moduleDoc.id}/${name}-${docType}.jade',
37+
});
38+
39+
computePathsProcessor.pathTemplates.push({
40+
docTypes: ['jade-data'],
41+
pathTemplate: '${originalDoc.id}/_data',
42+
outputPathTemplate: MODULES_DOCS_PATH + '/${path}.json'
43+
});
44+
})
45+
46+
.config(function(getLinkInfo) {
47+
getLinkInfo.relativeLinks = true;
48+
});

‎docs/angular.io-package/processors/addJadeDataDocsProcessor.js‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
var _ = require('lodash');
2+
var path = require('canonical-path');
3+
4+
var titleCase = function(text) {
5+
return text.replace(/(.)(.*)/, function(_, first, rest) {
6+
return first.toUpperCase() + rest;
7+
});
8+
};
9+
10+
/*
11+
* Create _data.json file for Harp pages
12+
*
13+
* http://harpjs.com/docs/development/metadata
14+
*
15+
* This method creates the meta data required for each page
16+
* such as the title, description, etc. This meta data is used
17+
* in the harp static site generator to create the title for headers
18+
* and the navigation used in the API docs
19+
*
20+
*/
21+
22+
module.exports = function addJadeDataDocsProcessor(EXPORT_DOC_TYPES) {
23+
return {
24+
$runAfter: ['adding-extra-docs', 'cloneExportedFromDocs'],
25+
$runBefore: ['extra-docs-added'],
26+
$process: function(docs) {
27+
var extraDocs = [];
28+
var modules = [];
29+
30+
31+
/*
32+
* Create Data for Modules
33+
*
34+
* Modules must be public and have content
35+
*/
36+
37+
_.forEach(docs, function(doc) {
38+
if (doc.docType === 'module' && doc.exports.length) {
39+
modules.push(doc);
40+
41+
// GET DATA FOR INDEX PAGE OF MODULE SECTION
42+
var indexPageInfo = [{
43+
name: 'index',
44+
title: _.map(path.basename(doc.fileInfo.baseName).split('_'), function(part) {
45+
return titleCase(part);
46+
}).join(' '),
47+
intro: doc.description.replace('"', '\"').replace(/\r?\n|\r/g,"")
48+
}];
49+
50+
// GET DATA FOR EACH PAGE (CLASS, VARS, FUNCTIONS)
51+
var modulePageInfo = _.map(doc.exports, function(exportDoc) {
52+
return {
53+
name: exportDoc.name + '-' + exportDoc.docType,
54+
title: exportDoc.name + ' ' + titleCase(exportDoc.docType)
55+
};
56+
});
57+
58+
//COMBINE PAGE DATA
59+
var allPageData = indexPageInfo.concat(modulePageInfo);
60+
61+
// PUSH DATA TO EXTRA DOCS ARRAY
62+
extraDocs.push({
63+
id: doc.id + "-data",
64+
docType: 'jade-data',
65+
originalDoc: doc,
66+
data: allPageData
67+
});
68+
}
69+
});
70+
71+
72+
return docs.concat(extraDocs);
73+
}
74+
};
75+
};

‎docs/angular.io-package/services/renderMarkdown.js‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
var marked = require('marked');
2+
var Encoder = require('node-html-encoder').Encoder;
3+
var html2jade = require('html2jade');
4+
var indentString = require('indent-string');
5+
var S = require('string');
6+
7+
// entity type encoder
8+
var encoder = new Encoder('entity');
9+
10+
11+
12+
/**
13+
* @dgService renderMarkdown
14+
* @description
15+
* Render the markdown in the given string as HTML.
16+
*/
17+
module.exports = function renderMarkdown(trimIndentation) {
18+
19+
var renderer = new marked.Renderer();
20+
21+
renderer.code = function(code, lang, escaped) {
22+
23+
var cssClasses = ['prettyprint', 'linenums'];
24+
var trimmedCode = trimIndentation(code);
25+
26+
if(lang) {
27+
if(lang=='html') {
28+
trimmedCode = encoder.htmlEncode(trimmedCode);
29+
}
30+
cssClasses.push(this.options.langPrefix + escape(lang, true));
31+
}
32+
33+
return 'pre(class="' + cssClasses.join(' ') + '")\n'
34+
+ indentString('code.\n', ' ', 2)
35+
+ trimmedCode;
36+
};
37+
38+
renderer.heading = function (text, level, raw) {
39+
var headingText = marked.Renderer.prototype.heading.call(renderer, text, level, raw);
40+
var title = 'h2 ' + S(headingText).stripTags().s;
41+
42+
if (level==2) {
43+
title = '.l-main-section\n' + indentString(title, ' ', 2) ;
44+
}
45+
46+
return title;
47+
};
48+
49+
return function(content) {
50+
return marked(content, { renderer: renderer });
51+
};
52+
};

‎docs/angular.io-package/templates/class.template.html‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{% include "lib/paramList.html" -%}
2+
{% extends 'layout/base.template.html' -%}
3+
4+
{% block body %}
5+
p.location-badge.
6+
exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
7+
defined in <a href="https://github.com/angular/angular/tree/master/modules/{$ doc.location.start.source.name $}.js#L{$ doc.location.start.line $}">{$ doc.location.start.source.name $}.js (line {$ doc.location.start.line $})</a>
8+
9+
:markdown
10+
{$ doc.description | indent(2, true) $}
11+
12+
{%- if doc.constructorDoc or doc.members.length -%}
13+
.l-main-section
14+
h2 Members
15+
16+
{%- if doc.constructorDoc %}
17+
.l-sub-section
18+
h3 {$ doc.constructorDoc.name $}
19+
20+
{% if doc.constructorDoc.params %}
21+
pre.prettyprint
22+
code.
23+
{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) | indent(4, true) | trim $}
24+
{% endif %}
25+
:markdown
26+
{$ doc.constructorDoc.description | indent(6, true) | replace('## Example', '') | replace('# Example', '') $}
27+
28+
29+
{% endif -%}
30+
31+
{%- for member in doc.members %}
32+
.l-sub-section
33+
h3 {$ member.name $}
34+
35+
{% if member.params %}
36+
pre.prettyprint
37+
code.
38+
{$ member.name $}{$ paramList(member.params) | indent(4, true) | trim $}
39+
{% endif %}
40+
:markdown
41+
{$ member.description | indent(6, true) | replace('## Example', '') | replace('# Example', '') $}
42+
43+
44+
45+
{% endfor %}
46+
{%- endif -%}
47+
48+
{% endblock %}

‎docs/angular.io-package/templates/function.template.html‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{% include "lib/paramList.html" -%}
2+
{% extends 'layout/base.template.html' -%}
3+
4+
{% block body %}
5+
.l-main-section
6+
h2(class="function export") {$ doc.name $}
7+
8+
p <code>{$ paramList(doc.parameters) $}</code>
9+
10+
p.location-badge.
11+
exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
12+
13+
:markdown
14+
{$ doc.description | indent(4, true) $}
15+
16+
{% endblock %}

‎docs/angular.io-package/templates/jade-data.template.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
{%- for item in doc.data %}
3+
"{$ item.name $}" : {
4+
"title" : "{$ item.title $}"{% if item.intro %},
5+
"intro" : "{$ item.intro $}"{% endif %}
6+
}{% if not loop.last %},{% endif %}
7+
{% endfor -%}
8+
}

‎docs/angular.io-package/templates/layout/base.template.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% block body %}{% endblock %}

‎docs/angular.io-package/templates/lib/paramList.html‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{% macro paramList(params) -%}
2+
{%- if params -%}
3+
({%- for param in params -%}
4+
{$ param | escape $}{% if not loop.last %}, {% endif %}
5+
{%- endfor %})
6+
{%- endif %}
7+
{%- endmacro -%}

‎docs/angular.io-package/templates/module.template.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{% extends 'layout/base.template.html' -%}
2+
{% block body -%}
3+
ul
4+
for page, slug in public.docs[current.path[1]][current.path[2]][current.path[3]][current.path[4]]._data
5+
if slug != 'index'
6+
url = "/docs/" + current.path[1] + "/" + current.path[2] + "/" + current.path[3] + "/" + current.path[4] + "/" + slug + ".html"
7+
8+
li.c8
9+
!= partial("../../../../../_includes/_hover-card", {name: page.title, url: url })
10+
11+
{% endblock %}

‎docs/angular.io-package/templates/var.template.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{% extends 'layout/base.template.html' %}
2+
3+
{% block body %}
4+
.l-main-section
5+
h2 {$ doc.name $} <span class="type">variable</span>
6+
p.location-badge.
7+
exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
8+
9+
:markdown
10+
{$ doc.description | indent(4, true) $}
11+
{% endblock %}

0 commit comments

Comments
 (0)