Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 2832a60

Browse filesBrowse files
tflanaganMyles Borins
tflanagan
authored and
Myles Borins
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 0149cb0 commit 2832a60
Copy full SHA for 2832a60

File tree

Expand file treeCollapse file tree

6 files changed

+95
-12
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

6 files changed

+95
-12
lines changed
Open diff view settings
Collapse file

‎doc/api_assets/style.css‎

Copy file name to clipboardExpand all lines: doc/api_assets/style.css
+13Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,19 @@ em code {
103103
background-color: #0084B6;
104104
}
105105

106+
.api_metadata {
107+
font-size: .75em;
108+
margin-bottom: 1em;
109+
}
110+
111+
.api_metadata span {
112+
margin-right: 1em;
113+
}
114+
115+
.api_metadata span:last-child {
116+
margin-right: 0px;
117+
}
118+
106119
ul.plain {
107120
list-style: none;
108121
}
Collapse file

‎tools/doc/README.md‎

Copy file name to clipboardExpand all lines: tools/doc/README.md
+27Lines changed: 27 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
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

Collapse file

‎tools/doc/common.js‎

Copy file name to clipboard
+21Lines 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;
Collapse file

‎tools/doc/generate.js‎

Copy file name to clipboardExpand all lines: tools/doc/generate.js
+6-6Lines 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(/^\-\-/)) {
Collapse file

‎tools/doc/html.js‎

Copy file name to clipboardExpand all lines: tools/doc/html.js
+21-5Lines 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']);
Collapse file

‎tools/doc/json.js‎

Copy file name to clipboardExpand all lines: tools/doc/json.js
+7-1Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.