Skip to content

Commit

Permalink
tools: parse documentation metadata
Browse files Browse the repository at this point in the history
This commit introduces the Documentation YAML metadata concept to the
documentation.

- Parses added or Added for HTML
- Parses all data for JSON

Ref: nodejs#3713
Ref: nodejs#6470
  • Loading branch information
tflanagan authored and addaleax committed May 4, 2016
1 parent aaff1b4 commit 7ee6bd1
Show file tree
Hide file tree
Showing 6 changed files with 95 additions and 12 deletions.
13 changes: 13 additions & 0 deletions doc/api_assets/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,19 @@ em code {
background-color: #0084B6;
}

.api_metadata {
font-size: .75em;
margin-bottom: 1em;
}

.api_metadata span {
margin-right: 1em;
}

.api_metadata span:last-child {
margin-right: 0px;
}

ul.plain {
list-style: none;
}
Expand Down
27 changes: 27 additions & 0 deletions tools/doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,27 @@ Each type of heading has a description block.


## module
<!-- YAML
added: v0.10.0
-->

Stability: 3 - Stable

description and examples.

### module.property
<!-- YAML
added: v0.10.0
-->

* Type

description of the property.

### module.someFunction(x, y, [z=100])
<!-- YAML
added: v0.10.0
-->

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

### Event: 'blerg'
<!-- YAML
added: v0.10.0
-->

* Argument: SomeClass object.

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

## Class: SomeClass
<!-- YAML
added: v0.10.0
-->

description of the class.

### Class Method: SomeClass.classMethod(anArg)
<!-- YAML
added: v0.10.0
-->

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

### someClass.nextSibling()
<!-- YAML
added: v0.10.0
-->

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

### someClass.someProperty
<!-- YAML
added: v0.10.0
-->

* String

The indication of what someProperty is.

### Event: 'grelb'
<!-- YAML
added: v0.10.0
-->

* `isBlerg` {Boolean}

Expand Down
21 changes: 21 additions & 0 deletions tools/doc/common.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
'use strict';

const yaml = require('js-yaml');

function isYAMLBlock(text) {
return !!text.match(/^<!-- YAML/);
}

exports.isYAMLBlock = isYAMLBlock;

function extractAndParseYAML(text) {
text = text.trim();

text = text.replace(/^<!-- YAML/, '')
.replace(/-->$/, '');

// js-yaml.safeLoad() throws on error
return yaml.safeLoad(text);
}

exports.extractAndParseYAML = extractAndParseYAML;
12 changes: 6 additions & 6 deletions tools/doc/generate.js
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
'use strict';

var processIncludes = require('./preprocess.js');
var fs = require('fs');
const processIncludes = require('./preprocess.js');
const fs = require('fs');

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

var args = process.argv.slice(2);
var format = 'json';
var template = null;
var inputFile = null;
const args = process.argv.slice(2);
let format = 'json';
let template = null;
let inputFile = null;

args.forEach(function(arg) {
if (!arg.match(/^\-\-/)) {
Expand Down
26 changes: 21 additions & 5 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
'use strict';

var fs = require('fs');
var marked = require('marked');
var path = require('path');
var preprocess = require('./preprocess.js');
var typeParser = require('./type-parser.js');
const common = require('./common.js');
const fs = require('fs');
const marked = require('marked');
const path = require('path');
const preprocess = require('./preprocess.js');
const typeParser = require('./type-parser.js');

module.exports = toHTML;

Expand Down Expand Up @@ -148,6 +149,9 @@ function parseLists(input) {
output.push(tok);
return;
}
if (tok.type === 'html' && common.isYAMLBlock(tok.text)) {
tok.text = parseYAML(tok.text);
}
state = null;
output.push(tok);
return;
Expand All @@ -174,6 +178,18 @@ function parseLists(input) {
return output;
}

function parseYAML(text) {
const meta = common.extractAndParseYAML(text);
let html = '<div class="api_metadata">';

if (meta.added || meta.Added) {
meta.added = meta.added || meta.Added;

html += '<span>Added: ' + meta.added + '</span>';
}

return html + '</div>';
}

// Syscalls which appear in the docs, but which only exist in BSD / OSX
var BSD_ONLY_SYSCALLS = new Set(['lchmod']);
Expand Down
8 changes: 7 additions & 1 deletion tools/doc/json.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ module.exports = doJSON;
// Take the lexed input, and return a JSON-encoded object
// A module looks like this: https://gist.github.com/1777387

var marked = require('marked');
const common = require('./common.js');
const marked = require('marked');

function doJSON(input, filename, cb) {
var root = {source: filename};
Expand Down Expand Up @@ -91,6 +92,8 @@ function doJSON(input, filename, cb) {
current.list = current.list || [];
current.list.push(tok);
current.list.level = 1;
} else if (type === 'html') {
current.meta = parseYAML(tok.text);
} else {
current.desc = current.desc || [];
if (!Array.isArray(current.desc)) {
Expand Down Expand Up @@ -274,6 +277,9 @@ function processList(section) {
delete section.list;
}

function parseYAML(text) {
return common.extractAndParseYAML(text);
}

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

0 comments on commit 7ee6bd1

Please sign in to comment.