Skip to content

tools: overhaul tools/doc/html.js #20613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vsemozhetbyt wants to merge 2 commits into from
Closed

tools: overhaul tools/doc/html.js #20613

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de08352
tools: overhaul tools/doc/html.js
vsemozhetbyt Apr 25, 2018
071e34a
fixup: reorder function declarations
vsemozhetbyt May 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
fixup: reorder function declarations
  • Loading branch information
@vsemozhetbyt
vsemozhetbyt committed May 8, 2018
commit 071e34a568588662c16ec3c1d5a36c03256ed18e
186 changes: 93 additions & 93 deletions tools/doc/html.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,51 +103,6 @@ function toHTML({ input, filename, nodeVersion, analytics }, cb) {
cb(null, HTML);
}

// Replace placeholders in text tokens.
function replaceInText(text) {
if (text === '') return text;
return linkJsTypeDocs(linkManPages(text));
}

function altDocs(filename, docCreated) {
const [, docCreatedMajor, docCreatedMinor] = docCreated.map(Number);
const host = 'https://nodejs.org';
const versions = [
{ num: '10.x' },
{ num: '9.x' },
{ num: '8.x', lts: true },
{ num: '7.x' },
{ num: '6.x', lts: true },
{ num: '5.x' },
{ num: '4.x', lts: true },
{ num: '0.12.x' },
{ num: '0.10.x' }
];

const getHref = (versionNum) =>
`${host}/docs/latest-v${versionNum}/api/${filename}.html`;

const wrapInListItem = (version) =>
`<li><a href="${getHref(version.num)}">${version.num}` +
`${version.lts ? ' <b>LTS</b>' : ''}</a></li>`;

function isDocInVersion(version) {
const [versionMajor, versionMinor] = version.num.split('.').map(Number);
if (docCreatedMajor > versionMajor) return false;
if (docCreatedMajor < versionMajor) return true;
return docCreatedMinor <= versionMinor;
}

const list = versions.filter(isDocInVersion).map(wrapInListItem).join('\n');

return list ? `
<li class="version-picker">
<a href="#">View another version <span>&#x25bc;</span></a>
<ol class="version-picker">${list}</ol>
</li>
` : '';
}

// Handle general body-text replacements.
// For example, link man page references to the actual page.
function preprocessText(lexed) {
Expand All @@ -168,6 +123,53 @@ function preprocessText(lexed) {
});
}

// Replace placeholders in text tokens.
function replaceInText(text) {
if (text === '') return text;
return linkJsTypeDocs(linkManPages(text));
}

// Syscalls which appear in the docs, but which only exist in BSD / macOS.
const BSD_ONLY_SYSCALLS = new Set(['lchmod']);
const MAN_PAGE = /(^|\s)([a-z.]+)\((\d)([a-z]?)\)/gm;

// Handle references to man pages, eg "open(2)" or "lchmod(2)".
// Returns modified text, with such refs replaced with HTML links, for example
// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'.
function linkManPages(text) {
return text.replace(
MAN_PAGE, (match, beginning, name, number, optionalCharacter) => {
// Name consists of lowercase letters,
// number is a single digit with an optional lowercase letter.
const displayAs = `${name}(${number}${optionalCharacter})`;

if (BSD_ONLY_SYSCALLS.has(name)) {
return `${beginning}<a href="https://www.freebsd.org/cgi/man.cgi` +
`?query=${name}&sektion=${number}">${displayAs}</a>`;
}
return `${beginning}<a href="http://man7.org/linux/man-pages/man${number}` +
`/${name}.${number}${optionalCharacter}.html">${displayAs}</a>`;
});
}

const TYPE_SIGNATURE = /\{[^}]+\}/g;
function linkJsTypeDocs(text) {
const parts = text.split('`');

// Handle types, for example the source Markdown might say
// "This argument should be a {number} or {string}".
for (let i = 0; i < parts.length; i += 2) {
const typeMatches = parts[i].match(TYPE_SIGNATURE);
if (typeMatches) {
typeMatches.forEach((typeMatch) => {
parts[i] = parts[i].replace(typeMatch, typeParser.toLink(typeMatch));
});
}
}

return parts.join('`');
}

// Preprocess stability blockquotes and YAML blocks.
function preprocessElements(lexed) {
const STABILITY_RE = /(.*:)\s*(\d)([\s\S]*)/;
Expand Down Expand Up @@ -257,45 +259,15 @@ function parseYAML(text) {
return html;
}

// Syscalls which appear in the docs, but which only exist in BSD / macOS.
const BSD_ONLY_SYSCALLS = new Set(['lchmod']);
const MAN_PAGE = /(^|\s)([a-z.]+)\((\d)([a-z]?)\)/gm;

// Handle references to man pages, eg "open(2)" or "lchmod(2)".
// Returns modified text, with such refs replaced with HTML links, for example
// '<a href="http://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>'.
function linkManPages(text) {
return text.replace(
MAN_PAGE, (match, beginning, name, number, optionalCharacter) => {
// Name consists of lowercase letters,
// number is a single digit with an optional lowercase letter.
const displayAs = `${name}(${number}${optionalCharacter})`;

if (BSD_ONLY_SYSCALLS.has(name)) {
return `${beginning}<a href="https://www.freebsd.org/cgi/man.cgi` +
`?query=${name}&sektion=${number}">${displayAs}</a>`;
}
return `${beginning}<a href="http://man7.org/linux/man-pages/man${number}` +
`/${name}.${number}${optionalCharacter}.html">${displayAs}</a>`;
});
}

const TYPE_SIGNATURE = /\{[^}]+\}/g;
function linkJsTypeDocs(text) {
const parts = text.split('`');

// Handle types, for example the source Markdown might say
// "This argument should be a {number} or {string}".
for (let i = 0; i < parts.length; i += 2) {
const typeMatches = parts[i].match(TYPE_SIGNATURE);
if (typeMatches) {
typeMatches.forEach((typeMatch) => {
parts[i] = parts[i].replace(typeMatch, typeParser.toLink(typeMatch));
});
}
}

return parts.join('`');
const numberRe = /^\d*/;
function versionSort(a, b) {
a = a.trim();
b = b.trim();
let i = 0; // Common prefix length.
while (i < a.length && i < b.length && a[i] === b[i]) i++;
a = a.substr(i);
b = b.substr(i);
return +b.match(numberRe)[0] - +a.match(numberRe)[0];
}

function buildToc(lexed, filename) {
Expand Down Expand Up @@ -354,13 +326,41 @@ function getId(text, idCounters) {
return text;
}

const numberRe = /^\d*/;
function versionSort(a, b) {
a = a.trim();
b = b.trim();
let i = 0; // Common prefix length.
while (i < a.length && i < b.length && a[i] === b[i]) i++;
a = a.substr(i);
b = b.substr(i);
return +b.match(numberRe)[0] - +a.match(numberRe)[0];
function altDocs(filename, docCreated) {
const [, docCreatedMajor, docCreatedMinor] = docCreated.map(Number);
const host = 'https://nodejs.org';
const versions = [
{ num: '10.x' },
{ num: '9.x' },
{ num: '8.x', lts: true },
{ num: '7.x' },
{ num: '6.x', lts: true },
{ num: '5.x' },
{ num: '4.x', lts: true },
{ num: '0.12.x' },
{ num: '0.10.x' }
];

const getHref = (versionNum) =>
`${host}/docs/latest-v${versionNum}/api/${filename}.html`;

const wrapInListItem = (version) =>
`<li><a href="${getHref(version.num)}">${version.num}` +
`${version.lts ? ' <b>LTS</b>' : ''}</a></li>`;

function isDocInVersion(version) {
const [versionMajor, versionMinor] = version.num.split('.').map(Number);
if (docCreatedMajor > versionMajor) return false;
if (docCreatedMajor < versionMajor) return true;
return docCreatedMinor <= versionMinor;
}

const list = versions.filter(isDocInVersion).map(wrapInListItem).join('\n');

return list ? `
<li class="version-picker">
<a href="#">View another version <span>&#x25bc;</span></a>
<ol class="version-picker">${list}</ol>
</li>
` : '';
}