FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

tools: parse documentation metadata · nodejs/node@cea1777 · GitHub

/ node Public

Commit cea1777

Browse files
tflanagan
authored and
evanlucas
committed
tools: parse documentation metadata
This commit introduces the Documentation YAML metadata concept to the documentation. - Parses added or Added for HTML - Parses all data for JSON Ref: #3867 Ref: #3713 Ref: #6470 PR-URL: #6495 Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
1 parent a568ad4 commit cea1777

6 files changed

Lines changed: 95 additions & 12 deletions

File tree

‎doc/api_assets/style.css‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,19 @@ em code {
108108
background-color: #0084B6;
109109
}
110110

111+
.api_metadata {
112+
font-size: .75em;
113+
margin-bottom: 1em;
114+
}
115+
116+
.api_metadata span {
117+
margin-right: 1em;
118+
}
119+
120+
.api_metadata span:last-child {
121+
margin-right: 0px;
122+
}
123+
111124
ul.plain {
112125
list-style: none;
113126
}

‎tools/doc/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,27 @@ Each type of heading has a description block.
66

77

88
## module
9+
<!-- YAML
10+
added: v0.10.0
11+
-->
912

1013
Stability: 3 - Stable
1114

1215
description and examples.
1316

1417
### module.property
18+
<!-- YAML
19+
added: v0.10.0
20+
-->
1521

1622
* Type
1723

1824
description of the property.
1925

2026
### module.someFunction(x, y, [z=100])
27+
<!-- YAML
28+
added: v0.10.0
29+
-->
2130

2231
* `x` {String} the description of the string
2332
* `y` {Boolean} Should I stay or should I go?
@@ -26,17 +35,26 @@ Each type of heading has a description block.
2635
A description of the function.
2736

2837
### Event: 'blerg'
38+
<!-- YAML
39+
added: v0.10.0
40+
-->
2941

3042
* Argument: SomeClass object.
3143

3244
Modules don't usually raise events on themselves. `cluster` is the
3345
only exception.
3446

3547
## Class: SomeClass
48+
<!-- YAML
49+
added: v0.10.0
50+
-->
3651

3752
description of the class.
3853

3954
### Class Method: SomeClass.classMethod(anArg)
55+
<!-- YAML
56+
added: v0.10.0
57+
-->
4058

4159
* `anArg` {Object} Just an argument
4260
* `field` {String} anArg can have this field.
@@ -46,16 +64,25 @@ Each type of heading has a description block.
4664
Description of the method for humans.
4765

4866
### someClass.nextSibling()
67+
<!-- YAML
68+
added: v0.10.0
69+
-->
4970

5071
* Return: {SomeClass object | null} The next someClass in line.
5172

5273
### someClass.someProperty
74+
<!-- YAML
75+
added: v0.10.0
76+
-->
5377

5478
* String
5579

5680
The indication of what someProperty is.
5781

5882
### Event: 'grelb'
83+
<!-- YAML
84+
added: v0.10.0
85+
-->
5986

6087
* `isBlerg` {Boolean}
6188

‎tools/doc/common.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
'use strict';
2+
3+
const yaml = require('js-yaml');
4+
5+
function isYAMLBlock(text) {
6+
return !!text.match(/^<!-- YAML/);
7+
}
8+
9+
exports.isYAMLBlock = isYAMLBlock;
10+
11+
function extractAndParseYAML(text) {
12+
text = text.trim();
13+
14+
text = text.replace(/^<!-- YAML/, '')
15+
.replace(/-->$/, '');
16+
17+
// js-yaml.safeLoad() throws on error
18+
return yaml.safeLoad(text);
19+
}
20+
21+
exports.extractAndParseYAML = extractAndParseYAML;

‎tools/doc/generate.js‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
'use strict';
22

3-
var processIncludes = require('./preprocess.js');
4-
var fs = require('fs');
3+
const processIncludes = require('./preprocess.js');
4+
const fs = require('fs');
55

66
// parse the args.
77
// Don't use nopt or whatever for this. It's simple enough.
88

9-
var args = process.argv.slice(2);
10-
var format = 'json';
11-
var template = null;
12-
var inputFile = null;
9+
const args = process.argv.slice(2);
10+
let format = 'json';
11+
let template = null;
12+
let inputFile = null;
1313

1414
args.forEach(function(arg) {
1515
if (!arg.match(/^\-\-/)) {

‎tools/doc/html.js‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
'use strict';
22

3-
var fs = require('fs');
4-
var marked = require('marked');
5-
var path = require('path');
6-
var preprocess = require('./preprocess.js');
7-
var typeParser = require('./type-parser.js');
3+
const common = require('./common.js');
4+
const fs = require('fs');
5+
const marked = require('marked');
6+
const path = require('path');
7+
const preprocess = require('./preprocess.js');
8+
const typeParser = require('./type-parser.js');
89

910
module.exports = toHTML;
1011

@@ -148,6 +149,9 @@ function parseLists(input) {
148149
output.push(tok);
149150
return;
150151
}
152+
if (tok.type === 'html' && common.isYAMLBlock(tok.text)) {
153+
tok.text = parseYAML(tok.text);
154+
}
151155
state = null;
152156
output.push(tok);
153157
return;
@@ -174,6 +178,18 @@ function parseLists(input) {
174178
return output;
175179
}
176180

181+
function parseYAML(text) {
182+
const meta = common.extractAndParseYAML(text);
183+
let html = '<div class="api_metadata">';
184+
185+
if (meta.added || meta.Added) {
186+
meta.added = meta.added || meta.Added;
187+
188+
html += '<span>Added: ' + meta.added + '</span>';
189+
}
190+
191+
return html + '</div>';
192+
}
177193

178194
// Syscalls which appear in the docs, but which only exist in BSD / OSX
179195
var BSD_ONLY_SYSCALLS = new Set(['lchmod']);

‎tools/doc/json.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ module.exports = doJSON;
55
// Take the lexed input, and return a JSON-encoded object
66
// A module looks like this: https://gist.github.com/1777387
77

8-
var marked = require('marked');
8+
const common = require('./common.js');
9+
const marked = require('marked');
910

1011
function doJSON(input, filename, cb) {
1112
var root = {source: filename};
@@ -91,6 +92,8 @@ function doJSON(input, filename, cb) {
9192
current.list = current.list || [];
9293
current.list.push(tok);
9394
current.list.level = 1;
95+
} else if (type === 'html' && common.isYAMLBlock(tok.text)) {
96+
current.meta = parseYAML(tok.text);
9497
} else {
9598
current.desc = current.desc || [];
9699
if (!Array.isArray(current.desc)) {
@@ -274,6 +277,9 @@ function processList(section) {
274277
delete section.list;
275278
}
276279

280+
function parseYAML(text) {
281+
return common.extractAndParseYAML(text);
282+
}
277283

278284
// textRaw = "someobject.someMethod(a[, b=100][, c])"
279285
function parseSignature(text, sig) {

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL