From cfb7329dda6dec5cb5966620d950f6387e4e2010 Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Tue, 1 Sep 2020 01:12:54 +0200 Subject: [PATCH 1/4] tools,doc: allow page titles to contain inline code Previously the HTML title would be cut to the first text node only. --- tools/doc/html.js | 10 +++++----- tools/doc/package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tools/doc/html.js b/tools/doc/html.js index 8428fb9f3cf66f..ec20255074810a 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -93,12 +93,12 @@ function toHTML({ input, content, filename, nodeVersion, versions }) { // Set the section name based on the first header. Default to 'Index'. function firstHeader() { return (tree, file) => { - file.section = 'Index'; - const heading = find(tree, { type: 'heading' }); - if (heading) { - const text = find(heading, { type: 'text' }); - if (text) file.section = text.value; + + if (heading?.children.length) { + file.section = heading.children.map(({ value }) => value).join(''); + } else { + file.section = 'Index'; } }; } diff --git a/tools/doc/package.json b/tools/doc/package.json index 23178fcbc10635..0f25e607ce08c7 100644 --- a/tools/doc/package.json +++ b/tools/doc/package.json @@ -4,7 +4,7 @@ "description": "Internal tool for generating Node.js API docs", "version": "0.0.0", "engines": { - "node": ">=12.10.0" + "node": ">=14.0.0" }, "dependencies": { "highlight.js": "^9.18.1", From 2518ba1da0b84746eb153e583171ca6170b7f1cc Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Tue, 1 Sep 2020 01:52:05 +0200 Subject: [PATCH 2/4] v12 compatible --- tools/doc/html.js | 2 +- tools/doc/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/doc/html.js b/tools/doc/html.js index ec20255074810a..af6f7b479f427a 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -95,7 +95,7 @@ function firstHeader() { return (tree, file) => { const heading = find(tree, { type: 'heading' }); - if (heading?.children.length) { + if (heading && heading.children.length) { file.section = heading.children.map(({ value }) => value).join(''); } else { file.section = 'Index'; diff --git a/tools/doc/package.json b/tools/doc/package.json index 0f25e607ce08c7..23178fcbc10635 100644 --- a/tools/doc/package.json +++ b/tools/doc/package.json @@ -4,7 +4,7 @@ "description": "Internal tool for generating Node.js API docs", "version": "0.0.0", "engines": { - "node": ">=14.0.0" + "node": ">=12.10.0" }, "dependencies": { "highlight.js": "^9.18.1", From 7734e5401e8be2bab563830dbf1d54d48502e5e8 Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Wed, 2 Sep 2020 11:43:04 +0200 Subject: [PATCH 3/4] Add tests and support for nested elements --- test/doctool/test-doctool-html.js | 36 +++++++++---------- .../fixtures/document_with_special_heading.md | 4 +++ tools/doc/html.js | 4 ++- 3 files changed, 24 insertions(+), 20 deletions(-) create mode 100644 test/fixtures/document_with_special_heading.md diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index b03bada053761f..d8f37362e3a5dc 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -9,7 +9,7 @@ try { } const assert = require('assert'); -const { readFile } = require('fs'); +const { readFile } = require('fs/promises'); const fixtures = require('../common/fixtures'); const { replaceLinks } = require('../../tools/doc/markdown.js'); const html = require('../../tools/doc/html.js'); @@ -58,11 +58,6 @@ function toHTML({ input, filename, nodeVersion, versions }) { // This HTML will be stripped of all whitespace because we don't currently // have an HTML parser. const testData = [ - { - file: fixtures.path('sample_document.md'), - html: '
  1. fish
  2. fish
' + - '
  • Redfish
  • Bluefish
' - }, { file: fixtures.path('order_of_end_tags_5873.md'), html: '

Static method: Buffer.from(array) ' + @@ -126,6 +121,10 @@ const testData = [ 'href="#foo_see_also" id="foo_see_also">#

Check' + 'out alsothis guide

' }, + { + file: fixtures.path('document_with_special_heading.md'), + html: 'Sample markdown with special heading |', + } ]; const spaces = /\s/g; @@ -140,21 +139,20 @@ const versions = [ { num: '0.12.x' }, { num: '0.10.x' }]; -testData.forEach(({ file, html }) => { +testData.forEach(async ({ file, html }) => { // Normalize expected data by stripping whitespace. const expected = html.replace(spaces, ''); - readFile(file, 'utf8', common.mustCall(async (err, input) => { - assert.ifError(err); - const output = toHTML({ input: input, - filename: 'foo', - nodeVersion: process.version, - versions: versions }); + const input = await readFile(file, 'utf8'); + + const output = toHTML({ input, + filename: 'foo', + nodeVersion: process.version, + versions }); - const actual = output.replace(spaces, ''); - // Assert that the input stripped of all whitespace contains the - // expected markup. - assert(actual.includes(expected), - `ACTUAL: ${actual}\nEXPECTED: ${expected}`); - })); + const actual = output.replace(spaces, ''); + // Assert that the input stripped of all whitespace contains the + // expected markup. + assert(actual.includes(expected), + `ACTUAL: ${actual}\nEXPECTED: ${expected}`); }); diff --git a/test/fixtures/document_with_special_heading.md b/test/fixtures/document_with_special_heading.md new file mode 100644 index 00000000000000..817ec936e9396d --- /dev/null +++ b/test/fixtures/document_with_special_heading.md @@ -0,0 +1,4 @@ +# Sample `markdown` with _special_ **heading** + +Sometimes heading contains more than just one text child, the current file is +there to test just that. diff --git a/tools/doc/html.js b/tools/doc/html.js index af6f7b479f427a..2181d3c237175c 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -96,7 +96,9 @@ function firstHeader() { const heading = find(tree, { type: 'heading' }); if (heading && heading.children.length) { - file.section = heading.children.map(({ value }) => value).join(''); + const recursiveTextContent = (node) => + node.value || node.children.map(recursiveTextContent).join(''); + file.section = recursiveTextContent(heading); } else { file.section = 'Index'; } From 202b80aaef44d4b3987defce71d8785e0b29ef50 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel <duhamelantoine1995@gmail.com> Date: Thu, 3 Sep 2020 04:46:36 -0400 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is> --- test/doctool/test-doctool-html.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index d8f37362e3a5dc..1608eb04970222 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -9,7 +9,7 @@ try { } const assert = require('assert'); -const { readFile } = require('fs/promises'); +const { readFileSync } = require('fs'); const fixtures = require('../common/fixtures'); const { replaceLinks } = require('../../tools/doc/markdown.js'); const html = require('../../tools/doc/html.js'); @@ -139,11 +139,11 @@ const versions = [ { num: '0.12.x' }, { num: '0.10.x' }]; -testData.forEach(async ({ file, html }) => { +testData.forEach(({ file, html }) => { // Normalize expected data by stripping whitespace. const expected = html.replace(spaces, ''); - const input = await readFile(file, 'utf8'); + const input = readFileSync(file, 'utf8'); const output = toHTML({ input, filename: 'foo',