Examples Generation - Inconsistent Example Titles #1980
Description
Before I go and fix #1914 I would like to bring consistence to the examples and fix the lint warnings during generation.
Generating any of the examples produces the lint warning:
[...]
examples/graph2d/20_shading.html:
Missing #title element in the body.
There have to be at least two headings (group and example name).
The title in the head doesn't match the title in the body.
head: Graph2d | Shading Example
body:
[...]At first, I was confused since the example seems to follow the guidelines.
<!doctype html>
<html>
<head>
<title>Graph2d | Shading Example</title>
[...]
</head>
<body>
<h2>Graph2d | Shading Example</h2>
[...]
</body>
</html>Looking at the generation code in vis-dev-utils however, it expects 2 nested elements within a container-element with id="title", which content is then joined with |.
/**
* Test if the example conforms to the conventions.
* @param path - The path to the example (used for identification in logs).
* @param page - The HTML to be linted.
* @returns True if everything's okay, false otherwise.
*/
function lintExample(path: string, page: cheerio.CheerioAPI): boolean {
let valid = true;
const msgs = [`${path}:`];
if (page("#title").length !== 1) {
msgs.push("Missing #title element in the body.");
valid = false;
}
if (page("#title > *").length < 2) {
msgs.push(
"There have to be at least two headings (group and example name).",
);
valid = false;
}
const headTitle = page("head > title").text().trim();
const bodyTitle = page("#title > *")
.map((_i, elem): string => cheerio.load([])(elem).text())
.get()
.join(" | ")
.trim();
if (headTitle !== bodyTitle) {
msgs.push(
"The title in the head doesn't match the title in the body.",
` head: ${headTitle}`,
` body: ${bodyTitle}`,
);
valid = false;
}Issues:
- Many of the vis-timeline examples don't have a title at all.
- Some titles only have the name of example or are missing the
|-character between the group- and example-name. - None of the titles I found seem to follow the expected element-structure.
So I need some clarity before I go ahead and fix the examples: What is the expected format of those titles, and how are they supposed to be structured from here on out?
I personally feel the easiest would be to follow the <h2>[Group] | [Example Name]</h2> as it currently is for most vis-graph2d examples.
And possibly not require it to have an id="title" and instead just look for the first <h2> element in the body and use it's contents.
In the end, It's up to you to decide how you want it.
Cheers Lukas