Skip to content

tools,doc: fix version picker in docs to show all available versions #33466

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
Trott wants to merge 2 commits into from
Closed

tools,doc: fix version picker in docs to show all available versions #33466

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f563fb2
tools,doc: move version picker to external file
Trott May 19, 2020
ee52f24
tools: move version picker script to main doc directory
Trott May 19, 2020
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
Next Next commit
tools,doc: move version picker to external file 
This is a first step towards ensuring that all relevant versions show up
in the version picker for all versions of the docs.

Refs: #32077
  • Loading branch information
@Trott
Trott committed May 19, 2020
commit f563fb2c4fff364cf4021ee0c00831d355042bca
10 changes: 8 additions & 2 deletions tools/doc/generate.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,14 +92,20 @@ async function main() {
.use(htmlStringify)
.process(input);

const myHtml = await html.toHTML({ input, content, filename, nodeVersion,
versions });
const myHtml = await html.toHTML(
{ input, content, filename, nodeVersion, versions }
);
const myVersionPicker = await html.versionPicker(
{ input, content, filename, nodeVersion, versions }
);
const basename = path.basename(filename, '.md');
const htmlTarget = path.join(outputDir, `${basename}.html`);
const jsonTarget = path.join(outputDir, `${basename}.json`);
const versionPickerTarget = path.join(outputDir, `.${basename}.versions.js`);

return Promise.allSettled([
fs.writeFile(htmlTarget, myHtml),
fs.writeFile(versionPickerTarget, myVersionPicker),
fs.writeFile(jsonTarget, JSON.stringify(content.json, null, 2)),
]);
}
Expand Down
39 changes: 30 additions & 9 deletions tools/doc/html.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ const path = require('path');
const typeParser = require('./type-parser.js');

module.exports = {
toHTML, firstHeader, preprocessText, preprocessElements, buildToc
toHTML, firstHeader, preprocessText, preprocessElements, buildToc,
versionPicker
};

const docPath = path.resolve(__dirname, '..', '..', 'doc');
Expand Down Expand Up @@ -62,12 +63,17 @@ const gtocHTML = unified()
const templatePath = path.join(docPath, 'template.html');
const template = fs.readFileSync(templatePath, 'utf8');

function toHTML({ input, content, filename, nodeVersion, versions }) {
function toHTML({ input,
content,
filename,
nodeVersion,
versions,
versionsPartial }) {
filename = path.basename(filename, '.md');

const id = filename.replace(/\W+/g, '-');

let HTML = template.replace('__ID__', id)
const HTML = template.replace('__ID__', id)
.replace(/__FILENAME__/g, filename)
.replace('__SECTION__', content.section)
.replace(/__VERSION__/g, nodeVersion)
Expand All @@ -79,14 +85,29 @@ function toHTML({ input, content, filename, nodeVersion, versions }) {

const docCreated = input.match(
/<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.[0-9]+\s*-->/);
if (docCreated) {
HTML = HTML.replace('__ALTDOCS__', altDocs(filename, docCreated, versions));
} else {
console.error(`Failed to add alternative version links to ${filename}`);
HTML = HTML.replace('__ALTDOCS__', '');
if (!docCreated) {
throw new Error(`required introduced_in comment not found in ${filename}`);
}

if (versionsPartial) {
const htmlPayload =
altDocs(filename, docCreated, versions).replace(/\n/g, ' ');
if (htmlPayload.includes("'")) {
// If this ever throws during a doc build, guess we'll need to add
// escaping.
throw new Error('not prepared for single quoted content');
}
return `document.write('${htmlPayload}')`;
}

return HTML;
const versionsJS = `.${filename}.versions.js`;
return HTML.replace('__ALTDOCS__', `<script src="${versionsJS}"></script>`);
}

function versionPicker({ input, content, filename, nodeVersion, versions }) {
return toHTML(
{ input, content, filename, nodeVersion, versions, versionsPartial: true }
);
}

// Set the section name based on the first header. Default to 'Index'.
Expand Down