From 9d4d228bb66ed086fa4b05ca1d9d93537b8e016a Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:20:47 +0200 Subject: [PATCH 01/17] doc, tools: extract linkManPages --- tools/doc/html.js | 21 ++------------------- tools/doc/lib/linkManPages.js | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+), 19 deletions(-) create mode 100644 tools/doc/lib/linkManPages.js diff --git a/tools/doc/html.js b/tools/doc/html.js index ef7d78d5b70ab3..5ac032ec38ecd8 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -7,6 +7,8 @@ const path = require('path'); const preprocess = require('./preprocess.js'); const typeParser = require('./type-parser.js'); +const linkManPages = require('./lib/linkManPages') + module.exports = toHTML; // customized heading without id attribute @@ -216,25 +218,6 @@ function parseYAML(text) { return html.join('\n'); } -// Syscalls which appear in the docs, but which only exist in BSD / OSX -var BSD_ONLY_SYSCALLS = new Set(['lchmod']); - -// Handle references to man pages, eg "open(2)" or "lchmod(2)" -// Returns modified text, with such refs replace with HTML links, for example -// 'open(2)' -function linkManPages(text) { - return text.replace(/ ([a-z]+)\((\d)\)/gm, function(match, name, number) { - // name consists of lowercase letters, number is a single digit - var displayAs = name + '(' + number + ')'; - if (BSD_ONLY_SYSCALLS.has(name)) { - return ' ' + displayAs + ''; - } else { - return ' ' + displayAs + ''; - } - }); -} function linkJsTypeDocs(text) { var parts = text.split('`'); diff --git a/tools/doc/lib/linkManPages.js b/tools/doc/lib/linkManPages.js new file mode 100644 index 00000000000000..00052ed43a2cde --- /dev/null +++ b/tools/doc/lib/linkManPages.js @@ -0,0 +1,19 @@ +// Syscalls which appear in the docs, but which only exist in BSD / OSX +var BSD_ONLY_SYSCALLS = new Set(['lchmod']); + +// Handle references to man pages, eg "open(2)" or "lchmod(2)" +// Returns modified text, with such refs replace with HTML links, for example +// 'open(2)' +module.exports = function linkManPages(text) { + return text.replace(/ ([a-z]+)\((\d)\)/gm, function(match, name, number) { + // name consists of lowercase letters, number is a single digit + var displayAs = name + '(' + number + ')'; + if (BSD_ONLY_SYSCALLS.has(name)) { + return ' ' + displayAs + ''; + } else { + return ' ' + displayAs + ''; + } + }); +} From 56ac6af59e8c76d9c79c3cd4c4d96d0c987960c5 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:22:22 +0200 Subject: [PATCH 02/17] doc: extract parseText --- tools/doc/html.js | 11 +---------- tools/doc/lib/parseText.js | 10 ++++++++++ 2 files changed, 11 insertions(+), 10 deletions(-) create mode 100644 tools/doc/lib/parseText.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 5ac032ec38ecd8..589ffb704e549e 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -8,6 +8,7 @@ const preprocess = require('./preprocess.js'); const typeParser = require('./type-parser.js'); const linkManPages = require('./lib/linkManPages') +const parseText = require('./lib/parseText') module.exports = toHTML; @@ -131,16 +132,6 @@ function render(lexed, filename, template, nodeVersion, cb) { }); } -// handle general body-text replacements -// for example, link man page references to the actual page -function parseText(lexed) { - lexed.forEach(function(tok) { - if (tok.text && tok.type !== 'code') { - tok.text = linkManPages(tok.text); - tok.text = linkJsTypeDocs(tok.text); - } - }); -} // just update the list item text in-place. // lists that come right after a heading are what we're after. diff --git a/tools/doc/lib/parseText.js b/tools/doc/lib/parseText.js new file mode 100644 index 00000000000000..e6d754a11fea8c --- /dev/null +++ b/tools/doc/lib/parseText.js @@ -0,0 +1,10 @@ +// handle general body-text replacements +// for example, link man page references to the actual page +module.exports = function parseText(lexed) { + lexed.forEach(function(tok) { + if (tok.text && tok.type !== 'code') { + tok.text = linkManPages(tok.text); + tok.text = linkJsTypeDocs(tok.text); + } + }); +} From eccdbfc4db7871998613d175cbe114328c7647c8 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:23:55 +0200 Subject: [PATCH 03/17] doc, tools: extract toHTML --- tools/doc/html.js | 35 +---------------------------------- tools/doc/lib/toHTML.js | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 34 deletions(-) create mode 100644 tools/doc/lib/toHTML.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 589ffb704e549e..64f0637238d9d0 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -9,6 +9,7 @@ const typeParser = require('./type-parser.js'); const linkManPages = require('./lib/linkManPages') const parseText = require('./lib/parseText') +const toHTML = require('./lib/toHTML') module.exports = toHTML; @@ -33,40 +34,6 @@ var gtocPath = path.resolve(path.join( var gtocLoading = null; var gtocData = null; -function toHTML(input, filename, template, nodeVersion, cb) { - if (typeof nodeVersion === 'function') { - cb = nodeVersion; - nodeVersion = null; - } - nodeVersion = nodeVersion || process.version; - - if (gtocData) { - return onGtocLoaded(); - } - - if (gtocLoading === null) { - gtocLoading = [onGtocLoaded]; - return loadGtoc(function(err, data) { - if (err) throw err; - gtocData = data; - gtocLoading.forEach(function(xs) { - xs(); - }); - }); - } - - if (gtocLoading) { - return gtocLoading.push(onGtocLoaded); - } - - function onGtocLoaded() { - var lexed = marked.lexer(input); - fs.readFile(template, 'utf8', function(er, template) { - if (er) return cb(er); - render(lexed, filename, template, nodeVersion, cb); - }); - } -} function loadGtoc(cb) { fs.readFile(gtocPath, 'utf8', function(err, data) { diff --git a/tools/doc/lib/toHTML.js b/tools/doc/lib/toHTML.js new file mode 100644 index 00000000000000..f5c5aabf959f1e --- /dev/null +++ b/tools/doc/lib/toHTML.js @@ -0,0 +1,34 @@ +module.exports = function toHTML(input, filename, template, nodeVersion, cb) { + if (typeof nodeVersion === 'function') { + cb = nodeVersion; + nodeVersion = null; + } + nodeVersion = nodeVersion || process.version; + + if (gtocData) { + return onGtocLoaded(); + } + + if (gtocLoading === null) { + gtocLoading = [onGtocLoaded]; + return loadGtoc(function(err, data) { + if (err) throw err; + gtocData = data; + gtocLoading.forEach(function(xs) { + xs(); + }); + }); + } + + if (gtocLoading) { + return gtocLoading.push(onGtocLoaded); + } + + function onGtocLoaded() { + var lexed = marked.lexer(input); + fs.readFile(template, 'utf8', function(er, template) { + if (er) return cb(er); + render(lexed, filename, template, nodeVersion, cb); + }); + } +} From fe25e1a3d130766cb6c2775fc153a767849ec510 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:26:40 +0200 Subject: [PATCH 04/17] doc, tools: extract loadGtoc --- tools/doc/html.js | 28 +--------------------------- tools/doc/lib/loadGtoc.js | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 27 deletions(-) create mode 100644 tools/doc/lib/loadGtoc.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 64f0637238d9d0..ec60954cfb6653 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -10,6 +10,7 @@ const typeParser = require('./type-parser.js'); const linkManPages = require('./lib/linkManPages') const parseText = require('./lib/parseText') const toHTML = require('./lib/toHTML') +const loadGtoc = require('./lib/loadGtoc') module.exports = toHTML; @@ -22,33 +23,6 @@ marked.setOptions({ renderer: renderer }); -// TODO(chrisdickinson): never stop vomitting / fix this. -var gtocPath = path.resolve(path.join( - __dirname, - '..', - '..', - 'doc', - 'api', - '_toc.md' -)); -var gtocLoading = null; -var gtocData = null; - - -function loadGtoc(cb) { - fs.readFile(gtocPath, 'utf8', function(err, data) { - if (err) return cb(err); - - preprocess(gtocPath, data, function(err, data) { - if (err) return cb(err); - - data = marked(data).replace(/ Date: Wed, 25 May 2016 16:28:05 +0200 Subject: [PATCH 05/17] doc, tools: extract toID --- tools/doc/html.js | 7 +------ tools/doc/lib/toID.js | 6 ++++++ 2 files changed, 7 insertions(+), 6 deletions(-) create mode 100644 tools/doc/lib/toID.js diff --git a/tools/doc/html.js b/tools/doc/html.js index ec60954cfb6653..51dd7f1628244f 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -11,6 +11,7 @@ const linkManPages = require('./lib/linkManPages') const parseText = require('./lib/parseText') const toHTML = require('./lib/toHTML') const loadGtoc = require('./lib/loadGtoc') +const toID = require('./lib/toID') module.exports = toHTML; @@ -24,12 +25,6 @@ marked.setOptions({ }); -function toID(filename) { - return filename - .replace('.html', '') - .replace(/[^\w\-]/g, '-') - .replace(/-+/g, '-'); -} function render(lexed, filename, template, nodeVersion, cb) { if (typeof nodeVersion === 'function') { diff --git a/tools/doc/lib/toID.js b/tools/doc/lib/toID.js new file mode 100644 index 00000000000000..408c625079e24e --- /dev/null +++ b/tools/doc/lib/toID.js @@ -0,0 +1,6 @@ +module.exports = function toID(filename) { + return filename + .replace('.html', '') + .replace(/[^\w\-]/g, '-') + .replace(/-+/g, '-'); +} From db06307421bf24d35b111bae827662578b054181 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:29:14 +0200 Subject: [PATCH 06/17] doc, tools: extract render --- tools/doc/html.js | 45 +---------------------------------------- tools/doc/lib/render.js | 41 +++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 44 deletions(-) create mode 100644 tools/doc/lib/render.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 51dd7f1628244f..42a7f87fa94817 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -12,6 +12,7 @@ const parseText = require('./lib/parseText') const toHTML = require('./lib/toHTML') const loadGtoc = require('./lib/loadGtoc') const toID = require('./lib/toID') +const render = require('./lib/render') module.exports = toHTML; @@ -25,50 +26,6 @@ marked.setOptions({ }); - -function render(lexed, filename, template, nodeVersion, cb) { - if (typeof nodeVersion === 'function') { - cb = nodeVersion; - nodeVersion = null; - } - - nodeVersion = nodeVersion || process.version; - - // get the section - var section = getSection(lexed); - - filename = path.basename(filename, '.md'); - - parseText(lexed); - lexed = parseLists(lexed); - - // generate the table of contents. - // this mutates the lexed contents in-place. - buildToc(lexed, filename, function(er, toc) { - if (er) return cb(er); - - var id = toID(path.basename(filename)); - - template = template.replace(/__ID__/g, id); - template = template.replace(/__FILENAME__/g, filename); - template = template.replace(/__SECTION__/g, section); - template = template.replace(/__VERSION__/g, nodeVersion); - template = template.replace(/__TOC__/g, toc); - template = template.replace( - /__GTOC__/g, - gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active') - ); - - // content has to be the last thing we do with - // the lexed tokens, because it's destructive. - const content = marked.parser(lexed); - template = template.replace(/__CONTENT__/g, content); - - cb(null, template); - }); -} - - // just update the list item text in-place. // lists that come right after a heading are what we're after. function parseLists(input) { diff --git a/tools/doc/lib/render.js b/tools/doc/lib/render.js new file mode 100644 index 00000000000000..ad2bb452fadde0 --- /dev/null +++ b/tools/doc/lib/render.js @@ -0,0 +1,41 @@ +module.exports = function render(lexed, filename, template, nodeVersion, cb) { + if (typeof nodeVersion === 'function') { + cb = nodeVersion; + nodeVersion = null; + } + + nodeVersion = nodeVersion || process.version; + + // get the section + var section = getSection(lexed); + + filename = path.basename(filename, '.md'); + + parseText(lexed); + lexed = parseLists(lexed); + + // generate the table of contents. + // this mutates the lexed contents in-place. + buildToc(lexed, filename, function(er, toc) { + if (er) return cb(er); + + var id = toID(path.basename(filename)); + + template = template.replace(/__ID__/g, id); + template = template.replace(/__FILENAME__/g, filename); + template = template.replace(/__SECTION__/g, section); + template = template.replace(/__VERSION__/g, nodeVersion); + template = template.replace(/__TOC__/g, toc); + template = template.replace( + /__GTOC__/g, + gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active') + ); + + // content has to be the last thing we do with + // the lexed tokens, because it's destructive. + const content = marked.parser(lexed); + template = template.replace(/__CONTENT__/g, content); + + cb(null, template); + }); +} From 22ce257aa814f6dc4f63a775028565fe94089523 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:30:33 +0200 Subject: [PATCH 07/17] doc, tools: extract parseLists --- tools/doc/html.js | 61 +------------------------------------ tools/doc/lib/parseLists.js | 60 ++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 60 deletions(-) create mode 100644 tools/doc/lib/parseLists.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 42a7f87fa94817..65a51d1195de80 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -13,6 +13,7 @@ const toHTML = require('./lib/toHTML') const loadGtoc = require('./lib/loadGtoc') const toID = require('./lib/toID') const render = require('./lib/render') +const parseLists = require('./lib/parseLists') module.exports = toHTML; @@ -26,66 +27,6 @@ marked.setOptions({ }); -// just update the list item text in-place. -// lists that come right after a heading are what we're after. -function parseLists(input) { - var state = null; - var depth = 0; - var output = []; - output.links = input.links; - input.forEach(function(tok) { - if (tok.type === 'code' && tok.text.match(/Stability:.*/g)) { - tok.text = parseAPIHeader(tok.text); - output.push({ type: 'html', text: tok.text }); - return; - } - if (state === null || - (state === 'AFTERHEADING' && tok.type === 'heading')) { - if (tok.type === 'heading') { - state = 'AFTERHEADING'; - } - output.push(tok); - return; - } - if (state === 'AFTERHEADING') { - if (tok.type === 'list_start') { - state = 'LIST'; - if (depth === 0) { - output.push({ type: 'html', text: '
' }); - } - depth++; - output.push(tok); - return; - } - if (tok.type === 'html' && common.isYAMLBlock(tok.text)) { - tok.text = parseYAML(tok.text); - } - state = null; - output.push(tok); - return; - } - if (state === 'LIST') { - if (tok.type === 'list_start') { - depth++; - output.push(tok); - return; - } - if (tok.type === 'list_end') { - depth--; - output.push(tok); - if (depth === 0) { - state = null; - output.push({ type: 'html', text: '
' }); - } - return; - } - } - output.push(tok); - }); - - return output; -} - function parseYAML(text) { const meta = common.extractAndParseYAML(text); const html = ['
']; diff --git a/tools/doc/lib/parseLists.js b/tools/doc/lib/parseLists.js new file mode 100644 index 00000000000000..ec5f20fd5926cd --- /dev/null +++ b/tools/doc/lib/parseLists.js @@ -0,0 +1,60 @@ + +// just update the list item text in-place. +// lists that come right after a heading are what we're after. +module.exports = function parseLists(input) { + var state = null; + var depth = 0; + var output = []; + output.links = input.links; + input.forEach(function(tok) { + if (tok.type === 'code' && tok.text.match(/Stability:.*/g)) { + tok.text = parseAPIHeader(tok.text); + output.push({ type: 'html', text: tok.text }); + return; + } + if (state === null || + (state === 'AFTERHEADING' && tok.type === 'heading')) { + if (tok.type === 'heading') { + state = 'AFTERHEADING'; + } + output.push(tok); + return; + } + if (state === 'AFTERHEADING') { + if (tok.type === 'list_start') { + state = 'LIST'; + if (depth === 0) { + output.push({ type: 'html', text: '
' }); + } + depth++; + output.push(tok); + return; + } + if (tok.type === 'html' && common.isYAMLBlock(tok.text)) { + tok.text = parseYAML(tok.text); + } + state = null; + output.push(tok); + return; + } + if (state === 'LIST') { + if (tok.type === 'list_start') { + depth++; + output.push(tok); + return; + } + if (tok.type === 'list_end') { + depth--; + output.push(tok); + if (depth === 0) { + state = null; + output.push({ type: 'html', text: '
' }); + } + return; + } + } + output.push(tok); + }); + + return output; +} From f760f8887727fc2a52ff12275bd10a7f107b707f Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:31:51 +0200 Subject: [PATCH 08/17] doc, tool: extract parseYAML --- tools/doc/html.js | 16 +--------------- tools/doc/lib/parseYAML.js | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 15 deletions(-) create mode 100644 tools/doc/lib/parseYAML.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 65a51d1195de80..067dcbf9b982c3 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -14,6 +14,7 @@ const loadGtoc = require('./lib/loadGtoc') const toID = require('./lib/toID') const render = require('./lib/render') const parseLists = require('./lib/parseLists') +const parseYAML = require('./lib/parseYAML') module.exports = toHTML; @@ -27,21 +28,6 @@ marked.setOptions({ }); -function parseYAML(text) { - const meta = common.extractAndParseYAML(text); - const html = ['
']; - - if (meta.added) { - html.push(`Added in: ${meta.added.join(', ')}`); - } - - if (meta.deprecated) { - html.push(`Deprecated since: ${meta.deprecated.join(', ')} `); - } - - html.push('
'); - return html.join('\n'); -} function linkJsTypeDocs(text) { diff --git a/tools/doc/lib/parseYAML.js b/tools/doc/lib/parseYAML.js new file mode 100644 index 00000000000000..3ea17d00cb4cb7 --- /dev/null +++ b/tools/doc/lib/parseYAML.js @@ -0,0 +1,15 @@ +module.exports = function parseYAML(text) { + const meta = common.extractAndParseYAML(text); + const html = ['
']; + + if (meta.added) { + html.push(`Added in: ${meta.added.join(', ')}`); + } + + if (meta.deprecated) { + html.push(`Deprecated since: ${meta.deprecated.join(', ')} `); + } + + html.push('
'); + return html.join('\n'); +} From 05c0e6c4bc9fb34f2c06416d811df67d1c888ddb Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:33:50 +0200 Subject: [PATCH 09/17] doc, tools: extract linkJsTypeDocs --- tools/doc/html.js | 22 +--------------------- tools/doc/lib/linkJsTypeDocs.js | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 21 deletions(-) create mode 100644 tools/doc/lib/linkJsTypeDocs.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 067dcbf9b982c3..5d0b45edecbb22 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -15,6 +15,7 @@ const toID = require('./lib/toID') const render = require('./lib/render') const parseLists = require('./lib/parseLists') const parseYAML = require('./lib/parseYAML') +const linkJsTypeDocs = require('./lib/linkJsTypeDocs') module.exports = toHTML; @@ -29,27 +30,6 @@ marked.setOptions({ - -function linkJsTypeDocs(text) { - var parts = text.split('`'); - var i; - var typeMatches; - - // Handle types, for example the source Markdown might say - // "This argument should be a {Number} or {String}" - for (i = 0; i < parts.length; i += 2) { - typeMatches = parts[i].match(/\{([^\}]+)\}/g); - if (typeMatches) { - typeMatches.forEach(function(typeMatch) { - parts[i] = parts[i].replace(typeMatch, typeParser.toLink(typeMatch)); - }); - } - } - - //XXX maybe put more stuff here? - return parts.join('`'); -} - function parseAPIHeader(text) { text = text.replace( /(.*:)\s(\d)([\s\S]*)/, diff --git a/tools/doc/lib/linkJsTypeDocs.js b/tools/doc/lib/linkJsTypeDocs.js new file mode 100644 index 00000000000000..667fe16d784f2a --- /dev/null +++ b/tools/doc/lib/linkJsTypeDocs.js @@ -0,0 +1,19 @@ +module.exports = function linkJsTypeDocs(text) { + var parts = text.split('`'); + var i; + var typeMatches; + + // Handle types, for example the source Markdown might say + // "This argument should be a {Number} or {String}" + for (i = 0; i < parts.length; i += 2) { + typeMatches = parts[i].match(/\{([^\}]+)\}/g); + if (typeMatches) { + typeMatches.forEach(function(typeMatch) { + parts[i] = parts[i].replace(typeMatch, typeParser.toLink(typeMatch)); + }); + } + } + + //XXX maybe put more stuff here? + return parts.join('`'); +} From 109a3d748e4b830870a509671530ccab6448f1a1 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:34:56 +0200 Subject: [PATCH 10/17] doc, tools: extract parseAPIHeader --- tools/doc/html.js | 10 +--------- tools/doc/lib/parseAPIHeader.js | 7 +++++++ 2 files changed, 8 insertions(+), 9 deletions(-) create mode 100644 tools/doc/lib/parseAPIHeader.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 5d0b45edecbb22..2987515fa67048 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -16,6 +16,7 @@ const render = require('./lib/render') const parseLists = require('./lib/parseLists') const parseYAML = require('./lib/parseYAML') const linkJsTypeDocs = require('./lib/linkJsTypeDocs') +const parseAPIHeader = require('./lib/parseAPIHeader') module.exports = toHTML; @@ -29,15 +30,6 @@ marked.setOptions({ }); - -function parseAPIHeader(text) { - text = text.replace( - /(.*:)\s(\d)([\s\S]*)/, - '
$1 $2$3
' - ); - return text; -} - // section is just the first heading function getSection(lexed) { for (var i = 0, l = lexed.length; i < l; i++) { diff --git a/tools/doc/lib/parseAPIHeader.js b/tools/doc/lib/parseAPIHeader.js new file mode 100644 index 00000000000000..e10f5b581423f1 --- /dev/null +++ b/tools/doc/lib/parseAPIHeader.js @@ -0,0 +1,7 @@ +module.exports = function parseAPIHeader(text) { + text = text.replace( + /(.*:)\s(\d)([\s\S]*)/, + '
$1 $2$3
' + ); + return text; +} From b222a7e2ef9b250395a746002771a4097d3c8a60 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:35:48 +0200 Subject: [PATCH 11/17] doc, tool: extract getSection --- tools/doc/html.js | 9 +-------- tools/doc/lib/getSection.js | 9 +++++++++ 2 files changed, 10 insertions(+), 8 deletions(-) create mode 100644 tools/doc/lib/getSection.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 2987515fa67048..697d45dc6f6901 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -17,6 +17,7 @@ const parseLists = require('./lib/parseLists') const parseYAML = require('./lib/parseYAML') const linkJsTypeDocs = require('./lib/linkJsTypeDocs') const parseAPIHeader = require('./lib/parseAPIHeader') +const getSection = require('./lib/getSection') module.exports = toHTML; @@ -30,14 +31,6 @@ marked.setOptions({ }); -// section is just the first heading -function getSection(lexed) { - for (var i = 0, l = lexed.length; i < l; i++) { - var tok = lexed[i]; - if (tok.type === 'heading') return tok.text; - } - return ''; -} function buildToc(lexed, filename, cb) { diff --git a/tools/doc/lib/getSection.js b/tools/doc/lib/getSection.js new file mode 100644 index 00000000000000..b1f20f5b3e704b --- /dev/null +++ b/tools/doc/lib/getSection.js @@ -0,0 +1,9 @@ + +// section is just the first heading +module.exports = function getSection(lexed) { + for (var i = 0, l = lexed.length; i < l; i++) { + var tok = lexed[i]; + if (tok.type === 'heading') return tok.text; + } + return ''; +} From 659788228a90d1669cdf827d7d07d4db3699e1ff Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:37:18 +0200 Subject: [PATCH 12/17] doc, tools: extrat buildToc --- tools/doc/html.js | 26 +------------------------- tools/doc/lib/buildToc.js | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 25 deletions(-) create mode 100644 tools/doc/lib/buildToc.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 697d45dc6f6901..146585817b6f69 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -18,6 +18,7 @@ const parseYAML = require('./lib/parseYAML') const linkJsTypeDocs = require('./lib/linkJsTypeDocs') const parseAPIHeader = require('./lib/parseAPIHeader') const getSection = require('./lib/getSection') +const buildToc = require('./lib/buildToc') module.exports = toHTML; @@ -31,31 +32,6 @@ marked.setOptions({ }); - - -function buildToc(lexed, filename, cb) { - var toc = []; - var depth = 0; - lexed.forEach(function(tok) { - if (tok.type !== 'heading') return; - if (tok.depth - depth > 1) { - return cb(new Error('Inappropriate heading level\n' + - JSON.stringify(tok))); - } - - depth = tok.depth; - var id = getId(filename + '_' + tok.text.trim()); - toc.push(new Array((depth - 1) * 2 + 1).join(' ') + - '* ' + - tok.text + ''); - tok.text += '#'; - }); - - toc = marked.parse(toc.join('\n')); - cb(null, toc); -} - var idCounters = {}; function getId(text) { text = text.toLowerCase(); diff --git a/tools/doc/lib/buildToc.js b/tools/doc/lib/buildToc.js new file mode 100644 index 00000000000000..c260df408bb9c0 --- /dev/null +++ b/tools/doc/lib/buildToc.js @@ -0,0 +1,23 @@ + +module.exports = function buildToc(lexed, filename, cb) { + var toc = []; + var depth = 0; + lexed.forEach(function(tok) { + if (tok.type !== 'heading') return; + if (tok.depth - depth > 1) { + return cb(new Error('Inappropriate heading level\n' + + JSON.stringify(tok))); + } + + depth = tok.depth; + var id = getId(filename + '_' + tok.text.trim()); + toc.push(new Array((depth - 1) * 2 + 1).join(' ') + + '* ' + + tok.text + ''); + tok.text += '#'; + }); + + toc = marked.parse(toc.join('\n')); + cb(null, toc); +} From 285d96629068632a79a24398c735e0fa5fc88759 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 16:39:01 +0200 Subject: [PATCH 13/17] doc, tools: extract getId --- tools/doc/html.js | 16 +--------------- tools/doc/lib/getId.js | 13 +++++++++++++ 2 files changed, 14 insertions(+), 15 deletions(-) create mode 100644 tools/doc/lib/getId.js diff --git a/tools/doc/html.js b/tools/doc/html.js index 146585817b6f69..f82b9941bb99a0 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -19,6 +19,7 @@ const linkJsTypeDocs = require('./lib/linkJsTypeDocs') const parseAPIHeader = require('./lib/parseAPIHeader') const getSection = require('./lib/getSection') const buildToc = require('./lib/buildToc') +const getId = require('./lib/getId') module.exports = toHTML; @@ -30,18 +31,3 @@ renderer.heading = function(text, level) { marked.setOptions({ renderer: renderer }); - - -var idCounters = {}; -function getId(text) { - text = text.toLowerCase(); - text = text.replace(/[^a-z0-9]+/g, '_'); - text = text.replace(/^_+|_+$/, ''); - text = text.replace(/^([^a-z])/, '_$1'); - if (idCounters.hasOwnProperty(text)) { - text += '_' + (++idCounters[text]); - } else { - idCounters[text] = 0; - } - return text; -} diff --git a/tools/doc/lib/getId.js b/tools/doc/lib/getId.js new file mode 100644 index 00000000000000..53fe799cb1f409 --- /dev/null +++ b/tools/doc/lib/getId.js @@ -0,0 +1,13 @@ +var idCounters = {}; +module.exports = function getId(text) { + text = text.toLowerCase(); + text = text.replace(/[^a-z0-9]+/g, '_'); + text = text.replace(/^_+|_+$/, ''); + text = text.replace(/^([^a-z])/, '_$1'); + if (idCounters.hasOwnProperty(text)) { + text += '_' + (++idCounters[text]); + } else { + idCounters[text] = 0; + } + return text; +} From 0d9d4a659f830837f54c865fe4899cb0f8c62e19 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 17:08:08 +0200 Subject: [PATCH 14/17] doc, tools: meet dependencies --- test/doctool/test-doctool-html.js | 2 +- tools/doc/generate.js | 2 +- tools/doc/html.js | 30 +----------------------------- tools/doc/lib/buildToc.js | 3 +++ tools/doc/lib/linkJsTypeDocs.js | 2 ++ tools/doc/lib/loadGtoc.js | 12 +++++++++--- tools/doc/lib/parseLists.js | 4 +++- tools/doc/lib/parseText.js | 2 ++ tools/doc/lib/parseYAML.js | 2 ++ tools/doc/lib/render.js | 10 +++++++++- tools/doc/lib/toHTML.js | 29 ++++++++++++++++++++++------- 11 files changed, 55 insertions(+), 43 deletions(-) diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index a8476b7234c9fa..832dbd5aa194c8 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -5,7 +5,7 @@ const assert = require('assert'); const fs = require('fs'); const path = require('path'); -const html = require('../../tools/doc/html.js'); +const html = require('../../tools/doc/html.js').toHTML; // Test data is a list of objects with two properties. // The file property is the file path. diff --git a/tools/doc/generate.js b/tools/doc/generate.js index 7df987e1cf78f9..348ad1224aaeed 100644 --- a/tools/doc/generate.js +++ b/tools/doc/generate.js @@ -48,7 +48,7 @@ function next(er, input) { break; case 'html': - require('./html.js')(input, inputFile, template, nodeVersion, + require('./html.js').toHTML(input, inputFile, template, nodeVersion, function(er, html) { if (er) throw er; console.log(html); diff --git a/tools/doc/html.js b/tools/doc/html.js index f82b9941bb99a0..eba991ab49c7ea 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -1,33 +1,5 @@ 'use strict'; - -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'); - -const linkManPages = require('./lib/linkManPages') -const parseText = require('./lib/parseText') const toHTML = require('./lib/toHTML') -const loadGtoc = require('./lib/loadGtoc') -const toID = require('./lib/toID') -const render = require('./lib/render') -const parseLists = require('./lib/parseLists') -const parseYAML = require('./lib/parseYAML') -const linkJsTypeDocs = require('./lib/linkJsTypeDocs') -const parseAPIHeader = require('./lib/parseAPIHeader') -const getSection = require('./lib/getSection') -const buildToc = require('./lib/buildToc') -const getId = require('./lib/getId') - -module.exports = toHTML; -// customized heading without id attribute -var renderer = new marked.Renderer(); -renderer.heading = function(text, level) { - return '' + text + '\n'; -}; -marked.setOptions({ - renderer: renderer -}); +module.exports.toHTML = toHTML; diff --git a/tools/doc/lib/buildToc.js b/tools/doc/lib/buildToc.js index c260df408bb9c0..4d6f98dadaa6f3 100644 --- a/tools/doc/lib/buildToc.js +++ b/tools/doc/lib/buildToc.js @@ -1,3 +1,6 @@ +const marked = require('marked') +const toID = require('./toID.js'); +const getId = require('./getId.js'); module.exports = function buildToc(lexed, filename, cb) { var toc = []; diff --git a/tools/doc/lib/linkJsTypeDocs.js b/tools/doc/lib/linkJsTypeDocs.js index 667fe16d784f2a..e4e406e5cead04 100644 --- a/tools/doc/lib/linkJsTypeDocs.js +++ b/tools/doc/lib/linkJsTypeDocs.js @@ -1,3 +1,5 @@ +const typeParser = require('../type-parser.js'); + module.exports = function linkJsTypeDocs(text) { var parts = text.split('`'); var i; diff --git a/tools/doc/lib/loadGtoc.js b/tools/doc/lib/loadGtoc.js index 534038d23de7bb..9b7e69562a76e7 100644 --- a/tools/doc/lib/loadGtoc.js +++ b/tools/doc/lib/loadGtoc.js @@ -1,17 +1,23 @@ +const path = require('path') +const fs = require('fs') +const marked = require('marked') +const preprocess = require('../preprocess.js'); +const toID = require('./toID.js'); // TODO(chrisdickinson): never stop vomitting / fix this. var gtocPath = path.resolve(path.join( __dirname, '..', '..', + '..', 'doc', 'api', '_toc.md' )); -var gtocLoading = null; -var gtocData = null; +global.global.gtocLoading = null; +global.gtocData = null; -module.epxorts = function loadGtoc(cb) { +exports.loadGtoc = (cb) => { fs.readFile(gtocPath, 'utf8', function(err, data) { if (err) return cb(err); diff --git a/tools/doc/lib/parseLists.js b/tools/doc/lib/parseLists.js index ec5f20fd5926cd..a99d75e813d1b3 100644 --- a/tools/doc/lib/parseLists.js +++ b/tools/doc/lib/parseLists.js @@ -1,4 +1,6 @@ - +const common = require('../common.js'); +const parseAPIHeader = require('./parseAPIHeader.js'); +const parseYAML = require('./parseYAML.js'); // just update the list item text in-place. // lists that come right after a heading are what we're after. module.exports = function parseLists(input) { diff --git a/tools/doc/lib/parseText.js b/tools/doc/lib/parseText.js index e6d754a11fea8c..0de9c5404c46e6 100644 --- a/tools/doc/lib/parseText.js +++ b/tools/doc/lib/parseText.js @@ -1,3 +1,5 @@ +const linkManPages = require('./linkManPages') +const linkJsTypeDocs = require('./linkJsTypeDocs') // handle general body-text replacements // for example, link man page references to the actual page module.exports = function parseText(lexed) { diff --git a/tools/doc/lib/parseYAML.js b/tools/doc/lib/parseYAML.js index 3ea17d00cb4cb7..db63a57a9cb97b 100644 --- a/tools/doc/lib/parseYAML.js +++ b/tools/doc/lib/parseYAML.js @@ -1,3 +1,5 @@ +const common = require('../common.js'); + module.exports = function parseYAML(text) { const meta = common.extractAndParseYAML(text); const html = ['
']; diff --git a/tools/doc/lib/render.js b/tools/doc/lib/render.js index ad2bb452fadde0..1503e33611348e 100644 --- a/tools/doc/lib/render.js +++ b/tools/doc/lib/render.js @@ -1,3 +1,11 @@ +const path = require('path') +const marked = require('marked') +const getSection = require('./getSection') +const parseText = require('./parseText') +const parseLists = require('./parseLists') +const buildToc = require('./buildToc') +const toID = require('./toID.js'); + module.exports = function render(lexed, filename, template, nodeVersion, cb) { if (typeof nodeVersion === 'function') { cb = nodeVersion; @@ -28,7 +36,7 @@ module.exports = function render(lexed, filename, template, nodeVersion, cb) { template = template.replace(/__TOC__/g, toc); template = template.replace( /__GTOC__/g, - gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active') + global.gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active') ); // content has to be the last thing we do with diff --git a/tools/doc/lib/toHTML.js b/tools/doc/lib/toHTML.js index f5c5aabf959f1e..9ce56bac9c4da9 100644 --- a/tools/doc/lib/toHTML.js +++ b/tools/doc/lib/toHTML.js @@ -1,3 +1,18 @@ +const fs = require('fs') +const loadGtoc = require('./loadGtoc').loadGtoc +const render = require('./render') +const marked = require('marked') + +// customized heading without id attribute +var renderer = new marked.Renderer(); +renderer.heading = function(text, level) { + return '' + text + '\n'; +}; +marked.setOptions({ + renderer: renderer +}); + + module.exports = function toHTML(input, filename, template, nodeVersion, cb) { if (typeof nodeVersion === 'function') { cb = nodeVersion; @@ -5,23 +20,23 @@ module.exports = function toHTML(input, filename, template, nodeVersion, cb) { } nodeVersion = nodeVersion || process.version; - if (gtocData) { + if (global.gtocData) { return onGtocLoaded(); } - if (gtocLoading === null) { - gtocLoading = [onGtocLoaded]; + if (global.gtocLoading === null) { + global.gtocLoading = [onGtocLoaded]; return loadGtoc(function(err, data) { if (err) throw err; - gtocData = data; - gtocLoading.forEach(function(xs) { + global.gtocData = data; + global.gtocLoading.forEach(function(xs) { xs(); }); }); } - if (gtocLoading) { - return gtocLoading.push(onGtocLoaded); + if (global.gtocLoading) { + return global.gtocLoading.push(onGtocLoaded); } function onGtocLoaded() { From 2816104b6fbe09ea2e286a718337bef059219d28 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 18:34:36 +0200 Subject: [PATCH 15/17] doc, tools: refactor tools -> satisfy eslint --- doc/guides/_toc.md | 11 +++++++++++ test/doctool/test-doctool-html.js | 2 ++ tools/doc/html.js | 5 +---- tools/doc/lib/buildToc.js | 6 +++--- tools/doc/lib/getId.js | 3 ++- tools/doc/lib/getSection.js | 4 ++-- tools/doc/lib/linkJsTypeDocs.js | 3 ++- tools/doc/lib/linkManPages.js | 3 ++- tools/doc/lib/loadGtoc.js | 9 +++++---- tools/doc/lib/parseAPIHeader.js | 3 ++- tools/doc/lib/parseLists.js | 3 ++- tools/doc/lib/parseText.js | 7 ++++--- tools/doc/lib/parseYAML.js | 3 ++- tools/doc/lib/render.js | 17 +++++++++-------- tools/doc/lib/toHTML.js | 11 ++++++----- tools/doc/lib/toID.js | 3 ++- 16 files changed, 57 insertions(+), 36 deletions(-) create mode 100644 doc/guides/_toc.md diff --git a/doc/guides/_toc.md b/doc/guides/_toc.md new file mode 100644 index 00000000000000..3c0c22ede141fd --- /dev/null +++ b/doc/guides/_toc.md @@ -0,0 +1,11 @@ +* [About these Docs](documentation.html) +* [Usage & Example](synopsis.html) + +
+ +* [Building Node With Ninja](building-node-with-ninja.html) + +
+ +* [GitHub Repo & Issue Tracker](https://github.com/nodejs/node) +* [Mailing List](http://groups.google.com/group/nodejs) diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index 832dbd5aa194c8..2aedafe35d58fe 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -5,6 +5,8 @@ const assert = require('assert'); const fs = require('fs'); const path = require('path'); +common.globalCheck = false; + const html = require('../../tools/doc/html.js').toHTML; // Test data is a list of objects with two properties. diff --git a/tools/doc/html.js b/tools/doc/html.js index eba991ab49c7ea..048fa65be9ec63 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -1,5 +1,2 @@ 'use strict'; -const marked = require('marked'); -const toHTML = require('./lib/toHTML') - -module.exports.toHTML = toHTML; +module.exports.toHTML = require('./lib/toHTML'); diff --git a/tools/doc/lib/buildToc.js b/tools/doc/lib/buildToc.js index 4d6f98dadaa6f3..d93a146ec8d5c7 100644 --- a/tools/doc/lib/buildToc.js +++ b/tools/doc/lib/buildToc.js @@ -1,5 +1,5 @@ -const marked = require('marked') -const toID = require('./toID.js'); +'use strict'; +const marked = require('marked'); const getId = require('./getId.js'); module.exports = function buildToc(lexed, filename, cb) { @@ -23,4 +23,4 @@ module.exports = function buildToc(lexed, filename, cb) { toc = marked.parse(toc.join('\n')); cb(null, toc); -} +}; diff --git a/tools/doc/lib/getId.js b/tools/doc/lib/getId.js index 53fe799cb1f409..0642262a8188dc 100644 --- a/tools/doc/lib/getId.js +++ b/tools/doc/lib/getId.js @@ -1,3 +1,4 @@ +'use strict'; var idCounters = {}; module.exports = function getId(text) { text = text.toLowerCase(); @@ -10,4 +11,4 @@ module.exports = function getId(text) { idCounters[text] = 0; } return text; -} +}; diff --git a/tools/doc/lib/getSection.js b/tools/doc/lib/getSection.js index b1f20f5b3e704b..0754766c6af47b 100644 --- a/tools/doc/lib/getSection.js +++ b/tools/doc/lib/getSection.js @@ -1,4 +1,4 @@ - +'use strict'; // section is just the first heading module.exports = function getSection(lexed) { for (var i = 0, l = lexed.length; i < l; i++) { @@ -6,4 +6,4 @@ module.exports = function getSection(lexed) { if (tok.type === 'heading') return tok.text; } return ''; -} +}; diff --git a/tools/doc/lib/linkJsTypeDocs.js b/tools/doc/lib/linkJsTypeDocs.js index e4e406e5cead04..7066333c9006ef 100644 --- a/tools/doc/lib/linkJsTypeDocs.js +++ b/tools/doc/lib/linkJsTypeDocs.js @@ -1,3 +1,4 @@ +'use strict'; const typeParser = require('../type-parser.js'); module.exports = function linkJsTypeDocs(text) { @@ -18,4 +19,4 @@ module.exports = function linkJsTypeDocs(text) { //XXX maybe put more stuff here? return parts.join('`'); -} +}; diff --git a/tools/doc/lib/linkManPages.js b/tools/doc/lib/linkManPages.js index 00052ed43a2cde..b221f7fa3a8a02 100644 --- a/tools/doc/lib/linkManPages.js +++ b/tools/doc/lib/linkManPages.js @@ -1,3 +1,4 @@ +'use strict'; // Syscalls which appear in the docs, but which only exist in BSD / OSX var BSD_ONLY_SYSCALLS = new Set(['lchmod']); @@ -16,4 +17,4 @@ module.exports = function linkManPages(text) { '/' + name + '.' + number + '.html">' + displayAs + ''; } }); -} +}; diff --git a/tools/doc/lib/loadGtoc.js b/tools/doc/lib/loadGtoc.js index 9b7e69562a76e7..44aae27195c73f 100644 --- a/tools/doc/lib/loadGtoc.js +++ b/tools/doc/lib/loadGtoc.js @@ -1,6 +1,7 @@ -const path = require('path') -const fs = require('fs') -const marked = require('marked') +'use strict'; +const path = require('path'); +const fs = require('fs'); +const marked = require('marked'); const preprocess = require('../preprocess.js'); const toID = require('./toID.js'); // TODO(chrisdickinson): never stop vomitting / fix this. @@ -30,4 +31,4 @@ exports.loadGtoc = (cb) => { return cb(null, data); }); }); -} +}; diff --git a/tools/doc/lib/parseAPIHeader.js b/tools/doc/lib/parseAPIHeader.js index e10f5b581423f1..5b1cb3b6c0ef2e 100644 --- a/tools/doc/lib/parseAPIHeader.js +++ b/tools/doc/lib/parseAPIHeader.js @@ -1,7 +1,8 @@ +'use strict'; module.exports = function parseAPIHeader(text) { text = text.replace( /(.*:)\s(\d)([\s\S]*)/, '
$1 $2$3
' ); return text; -} +}; diff --git a/tools/doc/lib/parseLists.js b/tools/doc/lib/parseLists.js index a99d75e813d1b3..f737443afef2d8 100644 --- a/tools/doc/lib/parseLists.js +++ b/tools/doc/lib/parseLists.js @@ -1,3 +1,4 @@ +'use strict'; const common = require('../common.js'); const parseAPIHeader = require('./parseAPIHeader.js'); const parseYAML = require('./parseYAML.js'); @@ -59,4 +60,4 @@ module.exports = function parseLists(input) { }); return output; -} +}; diff --git a/tools/doc/lib/parseText.js b/tools/doc/lib/parseText.js index 0de9c5404c46e6..09d07ef611121b 100644 --- a/tools/doc/lib/parseText.js +++ b/tools/doc/lib/parseText.js @@ -1,5 +1,6 @@ -const linkManPages = require('./linkManPages') -const linkJsTypeDocs = require('./linkJsTypeDocs') +'use strict'; +const linkManPages = require('./linkManPages'); +const linkJsTypeDocs = require('./linkJsTypeDocs'); // handle general body-text replacements // for example, link man page references to the actual page module.exports = function parseText(lexed) { @@ -9,4 +10,4 @@ module.exports = function parseText(lexed) { tok.text = linkJsTypeDocs(tok.text); } }); -} +}; diff --git a/tools/doc/lib/parseYAML.js b/tools/doc/lib/parseYAML.js index db63a57a9cb97b..4f161f3bd7ccf8 100644 --- a/tools/doc/lib/parseYAML.js +++ b/tools/doc/lib/parseYAML.js @@ -1,3 +1,4 @@ +'use strict'; const common = require('../common.js'); module.exports = function parseYAML(text) { @@ -14,4 +15,4 @@ module.exports = function parseYAML(text) { html.push('
'); return html.join('\n'); -} +}; diff --git a/tools/doc/lib/render.js b/tools/doc/lib/render.js index 1503e33611348e..6d1d190968c5da 100644 --- a/tools/doc/lib/render.js +++ b/tools/doc/lib/render.js @@ -1,9 +1,10 @@ -const path = require('path') -const marked = require('marked') -const getSection = require('./getSection') -const parseText = require('./parseText') -const parseLists = require('./parseLists') -const buildToc = require('./buildToc') +'use strict'; +const path = require('path'); +const marked = require('marked'); +const getSection = require('./getSection'); +const parseText = require('./parseText'); +const parseLists = require('./parseLists'); +const buildToc = require('./buildToc'); const toID = require('./toID.js'); module.exports = function render(lexed, filename, template, nodeVersion, cb) { @@ -36,7 +37,7 @@ module.exports = function render(lexed, filename, template, nodeVersion, cb) { template = template.replace(/__TOC__/g, toc); template = template.replace( /__GTOC__/g, - global.gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active') + global.gtocData.replace(`class="nav-${id}`, `class="nav-${id} active`) ); // content has to be the last thing we do with @@ -46,4 +47,4 @@ module.exports = function render(lexed, filename, template, nodeVersion, cb) { cb(null, template); }); -} +}; diff --git a/tools/doc/lib/toHTML.js b/tools/doc/lib/toHTML.js index 9ce56bac9c4da9..ca74b1c66d1bd8 100644 --- a/tools/doc/lib/toHTML.js +++ b/tools/doc/lib/toHTML.js @@ -1,7 +1,8 @@ -const fs = require('fs') -const loadGtoc = require('./loadGtoc').loadGtoc -const render = require('./render') -const marked = require('marked') +'use strict'; +const fs = require('fs'); +const loadGtoc = require('./loadGtoc').loadGtoc; +const render = require('./render'); +const marked = require('marked'); // customized heading without id attribute var renderer = new marked.Renderer(); @@ -46,4 +47,4 @@ module.exports = function toHTML(input, filename, template, nodeVersion, cb) { render(lexed, filename, template, nodeVersion, cb); }); } -} +}; diff --git a/tools/doc/lib/toID.js b/tools/doc/lib/toID.js index 408c625079e24e..3c92eb33950497 100644 --- a/tools/doc/lib/toID.js +++ b/tools/doc/lib/toID.js @@ -1,6 +1,7 @@ +'use strict'; module.exports = function toID(filename) { return filename .replace('.html', '') .replace(/[^\w\-]/g, '-') .replace(/-+/g, '-'); -} +}; From c58bfb16d7f40d10bde93fa2cfeb29cda317c1ac Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Wed, 25 May 2016 19:46:00 +0200 Subject: [PATCH 16/17] doc, tools: have fs.writeFile gen html --- Makefile | 2 +- tools/doc/generate.js | 14 ++++++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 9a5bbf2f79c497..7dd885f02d0791 100644 --- a/Makefile +++ b/Makefile @@ -284,7 +284,7 @@ out/doc/api/%.json: doc/api/%.md [ -x $(NODE) ] && $(NODE) $(gen-json) || node $(gen-json) # check if ./node is actually set, else use user pre-installed binary -gen-html = tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< > $@ +gen-html = tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< out/doc/api/%.html: doc/api/%.md [ -x $(NODE) ] && $(NODE) $(gen-html) || node $(gen-html) diff --git a/tools/doc/generate.js b/tools/doc/generate.js index 348ad1224aaeed..29bb36442d7572 100644 --- a/tools/doc/generate.js +++ b/tools/doc/generate.js @@ -2,6 +2,8 @@ const processIncludes = require('./preprocess.js'); const fs = require('fs'); +const path = require('path'); +const toHTML = require('./html.js').toHTML; // parse the args. // Don't use nopt or whatever for this. It's simple enough. @@ -48,11 +50,15 @@ function next(er, input) { break; case 'html': - require('./html.js').toHTML(input, inputFile, template, nodeVersion, - function(er, html) { - if (er) throw er; - console.log(html); + toHTML(input, inputFile, template, nodeVersion, (er, html) => { + if (er) throw er; + const filename = `./out/doc/api/${path.basename(inputFile, 'md')}html`; + fs.writeFile(filename, html, (err) => { + if (err) + console.log(err); + console.log('generated:', filename); }); + }); break; default: From 206a84a5928a8ed09048c2172759308c1493fd44 Mon Sep 17 00:00:00 2001 From: Robert Jefe Lindstaedt Date: Thu, 26 May 2016 15:18:19 +0200 Subject: [PATCH 17/17] doc, tools: rebase from #6943 --- test/doctool/test-doctool-html.js | 40 ++++++++++++++++++++++++------- tools/doc/lib/buildToc.js | 17 ++++++++++++- tools/doc/preprocess.js | 5 +++- 3 files changed, 51 insertions(+), 11 deletions(-) diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index 2aedafe35d58fe..75360362dcf144 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -7,6 +7,7 @@ const path = require('path'); common.globalCheck = false; +const processIncludes = require('../../tools/doc/preprocess.js'); const html = require('../../tools/doc/html.js').toHTML; // Test data is a list of objects with two properties. @@ -55,22 +56,43 @@ const testData = [ '

Describe Something in more detail here. ' + '

' }, + { + file: path.join(common.fixturesDir, 'doc_with_includes.md'), + html: '' + + '

Look here!

' + + '' + + '' + + '

foobar#

' + + '

I exist and am being linked to.

' + + '' + }, ]; testData.forEach(function(item) { // Normalize expected data by stripping whitespace const expected = item.html.replace(/\s/g, ''); - fs.readFile(item.file, 'utf8', common.mustCall(function(err, input) { + fs.readFile(item.file, 'utf8', common.mustCall((err, input) => { assert.ifError(err); - html(input, 'foo', 'doc/template.html', - common.mustCall(function(err, output) { - assert.ifError(err); + processIncludes(item.file, input, common.mustCall((err, preprocessed) => { + assert.ifError(err); + + html( + { + input: preprocessed, + filename: 'foo', + template: 'doc/template.html', + nodeVersion: process.version, + }, + common.mustCall((err, output) => { + assert.ifError(err); - const actual = output.replace(/\s/g, ''); - // Assert that the input stripped of all whitespace contains the - // expected list - assert.notEqual(actual.indexOf(expected), -1); - })); + const actual = output.replace(/\s/g, ''); + // Assert that the input stripped of all whitespace contains the + // expected list + assert.notEqual(actual.indexOf(expected), -1); + })); + })); })); }); diff --git a/tools/doc/lib/buildToc.js b/tools/doc/lib/buildToc.js index d93a146ec8d5c7..2a62eff7368bd4 100644 --- a/tools/doc/lib/buildToc.js +++ b/tools/doc/lib/buildToc.js @@ -5,7 +5,21 @@ const getId = require('./getId.js'); module.exports = function buildToc(lexed, filename, cb) { var toc = []; var depth = 0; + + const startIncludeRefRE = /^\s*\s*$/; + const endIncludeRefRE = /^\s*\s*$/; + const realFilenames = [filename]; + lexed.forEach(function(tok) { + // Keep track of the current filename along @include directives. + if (tok.type === 'html') { + let match; + if ((match = tok.text.match(startIncludeRefRE)) !== null) + realFilenames.unshift(match[1]); + else if (tok.text.match(endIncludeRefRE)) + realFilenames.shift(); + } + if (tok.type !== 'heading') return; if (tok.depth - depth > 1) { return cb(new Error('Inappropriate heading level\n' + @@ -13,7 +27,8 @@ module.exports = function buildToc(lexed, filename, cb) { } depth = tok.depth; - var id = getId(filename + '_' + tok.text.trim()); + const realFilename = path.basename(realFilenames[0], '.md'); + const id = getId(realFilename + '_' + tok.text.trim()); toc.push(new Array((depth - 1) * 2 + 1).join(' ') + '* ' + tok.text + ''); diff --git a/tools/doc/preprocess.js b/tools/doc/preprocess.js index 295737a2a53aee..ad5a19af799fc0 100644 --- a/tools/doc/preprocess.js +++ b/tools/doc/preprocess.js @@ -48,7 +48,10 @@ function processIncludes(inputFile, input, cb) { if (errState) return; if (er) return cb(errState = er); incCount--; - includeData[fname] = inc; + // Add comments to let the HTML generator know how the anchors for + // headings should look like. + includeData[fname] = `\n` + + inc + `\n\n`; input = input.split(include + '\n').join(includeData[fname] + '\n'); if (incCount === 0) { return cb(null, input);