Skip to content
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

Improve documentation #1713

Merged
merged 7 commits into from
Mar 1, 2019
Merged

Improve documentation #1713

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
393a289
Check for empty descriptions on the latest schema
dgageot Mar 1, 2019
4996307
Simplify code
dgageot Mar 1, 2019
df30c04
Add some more validation
dgageot Mar 1, 2019
3e6ddca
Cleanup annotated yaml generation code
dgageot Mar 1, 2019
1482374
Improve rendering of alpha/beta
dgageot Mar 1, 2019
5daf0dc
Remove EOL from html descriptions
dgageot Mar 1, 2019
b2a6741
Shorter descriptions
dgageot Mar 1, 2019
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
12 changes: 10 additions & 2 deletions docs/content/en/docs/references/yaml/main.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,11 @@ td:first-child {
padding: 1px 5px !important;
}

td.top {
tr.top td {
background-color: #EEE;
}

td.top .comment {
tr.top .comment {
color: gray;
}

Expand All @@ -65,3 +65,11 @@ code {
border-radius: 3px;
padding: 0 .2em;
}

em {
font-family: unset;
font-size: 85%;
border: 1px dotted gray;
border-radius: 3px;
padding: 0 .2em;
}
268 changes: 144 additions & 124 deletions docs/content/en/docs/references/yaml/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,173 +3,193 @@ import { unsafeHTML } from "https://unpkg.com/lit-html@1.0.0/directives/unsafe-h

var version;
(async function() {
let l = new URL(import.meta.url);
version = l.hash.replace('#skaffold/', '');

const response = await fetch(`/schemas/${version}.json`);
const json = await response.json();
const url = new URL(import.meta.url);
version = url.hash.replace("#skaffold/", "");

const response = await fetch(`/schemas/${version}.json`);
const json = await response.json();
const table = document.getElementById("table");

render(html`${template(json.definitions, undefined, '#/definitions/SkaffoldPipeline', 0)}`, document.getElementById("table"));
render(html`
${template(json.definitions, undefined, '#/definitions/SkaffoldPipeline', 0)}
`, table);
})();

function* template(definitions, parentDefinition, ref, ident) {
const name = ref.replace('#/definitions/', '');

let allProperties = [];
let seen = {}
if (definitions[name].properties) {
var properties = definitions[name].properties;
for (var key of definitions[name].preferredOrder) {
allProperties.push([key, properties[key]]);
seen[key] = true;
}
const name = ref.replace("#/definitions/", "");
const allProperties = [];
const seen = {};

const properties = definitions[name].properties;
for (const key of (definitions[name].preferredOrder || [])) {
allProperties.push([key, properties[key]]);
seen[key] = true;
}
if (definitions[name].anyOf) {
for (var anyOf of definitions[name].anyOf) {
if (anyOf.preferredOrder) {
for (var key of anyOf.preferredOrder) {
if (!seen[key]) {
allProperties.push([key, anyOf.properties[key]]);
seen[key] = true;
}
}
}
}

const anyOfs = definitions[name].anyOf;
for (const anyOf of (anyOfs || [])) {
for (const key of (anyOf.preferredOrder || [])) {
if (seen[key]) continue;

allProperties.push([key, anyOf.properties[key]]);
seen[key] = true;
}
}

let index = -1
let index = -1;
for (var [key, definition] of allProperties) {
var desc = definition['x-intellij-html-description'];
let value = definition.default;
index++;

if (key === 'apiVersion') {
value = `skaffold/${version}`
}
if (definition.examples) {
value = definition.examples[0]
}
let valueClass = definition.examples ? 'example' : 'value';

let required = false;
if (definitions[name].required) {
for (var requiredName of definitions[name].required) {
if (requiredName === key) {
required = true;
break;
}
}
// Key
let required = definitions[name].required && definitions[name].required.includes(key);
let keyClass = required ? "key required" : "key";

// Value
let value = definition.default;
if (key === "apiVersion") {
value = `skaffold/${version}`;
} else if (definition.examples && definition.examples.length > 0) {
value = definition.examples[0];
}
let keyClass = required ? 'key required' : 'key';
let valueClass = definition.examples ? "example" : "value";

// Description
const desc = definition["x-intellij-html-description"];

// Special case for profiles
if (name === 'Profile') {
if ((key === 'build') || (key === 'test') || (key === 'deploy')) {
yield html`
<tr>
<td><span class="key" style="margin-left: ${ident * 20}px">${key}:</span> <span class="value">{}</span></td>
<td><span class="comment">#</span></td>
<td><span class="comment">${unsafeHTML(desc)}</span></td>
</tr>
`;
continue
}
if ((name === "Profile") && (key === "build" || key === "test" || key === "deploy")) {
value = "{}";
yield html`
<tr>
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
<span class="${valueClass}">${value}</span>
</td>
<td><span class="comment">#&nbsp;</span></td>
<td><span class="comment">${unsafeHTML(desc)}</span></td>
</tr>
`;
continue;
}

if (definition.$ref) {
// Check if the referenced description is a final one
const refName = definition.$ref.replace('#/definitions/', '');
if (!definitions[refName].properties && !definitions[refName].anyOf) {
value = '{}'
}
// Check if the referenced description is a final one
const refName = definition.$ref.replace("#/definitions/", "");
if (!definitions[refName].properties && !definitions[refName].anyOf) {
value = "{}";
}

yield html`
<tr>
<td class="top"><span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span> <span class="${valueClass}">${value}</span></td>
<td class="top"><span class="comment">#&nbsp;</span></td>
<td class="top"><span class="comment">${unsafeHTML(desc)}</span></td>
yield html`
<tr class="top">
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
<span class="${valueClass}">${value}</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment">${unsafeHTML(desc)}</td>
</tr>
`;
`;
} else if (definition.items && definition.items.$ref) {
yield html`
<tr>
<td class="top"><span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span> <span class="${valueClass}">${value}</span></td>
<td class="top"><span class="comment">#&nbsp;</span></td>
<td class="top"><span class="comment">${unsafeHTML(desc)}</span></td>
yield html`
<tr class="top">
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
<span class="${valueClass}">${value}</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment">${unsafeHTML(desc)}</td>
</tr>
`;
} else if (parentDefinition && parentDefinition.type === 'array' && (index == 0)) {
yield html`
`;
} else if (parentDefinition && (parentDefinition.type === "array") && (index == 0)) {
yield html`
<tr>
<td><span class="${keyClass}" style="margin-left: ${(ident - 1) * 20}px">- ${key}:</span> <span class="${valueClass}">${value}</span></td>
<td><span class="comment">#&nbsp;</span></td>
<td><span class="comment">${unsafeHTML(desc)}</span></td>
<td>
<span class="${keyClass}" style="margin-left: ${(ident - 1) * 20}px">- ${key}:</span>
<span class="${valueClass}">${value}</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment">${unsafeHTML(desc)}</td>
</tr>
`;
} else if ((definition.type === 'array') && value && (value != '[]')) {
// Parse value to json array
let values = JSON.parse(value);
`;
} else if ((definition.type === "array") && value && (value != "[]")) {
// Parse value to json array
const values = JSON.parse(value);

yield html`
yield html`
<tr>
<td><span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span></td>
<td><span class="comment">#&nbsp;</span></td>
<td rowspan="${1 + values.length}"><span class="comment">${unsafeHTML(desc)}</span></td>
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment" rowspan="${1 + values.length}">
${unsafeHTML(desc)}
</td>
</tr>
`;

for (var v of values) {
yield html`
<tr>
<td><span class="key" style="margin-left: ${ident * 20}px">- <span class="${valueClass}">${v}</span></span></td>
<td><span class="comment">#&nbsp;</span></td>
</tr>
`;
}
} else if ((definition.type === 'object') && value && (value != '{}')) {
// Parse value to json object
let values = JSON.parse(value);
`;

for (const v of values) {
yield html`
<tr>
<td>
<span class="key" style="margin-left: ${ident * 20}px">- <span class="${valueClass}">${v}</span></span>
</td>
<td class="comment">#&nbsp;</td>
</tr>
`;
}
} else if (definition.type === "object" && value && value != "{}") {
// Parse value to json object
const values = JSON.parse(value);

yield html`
<tr>
<td><span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span></td>
<td><span class="comment">#&nbsp;</span></td>
<td rowspan="${1 + Object.keys(values).length}"><span class="comment">${unsafeHTML(desc)}</span></td>
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment" rowspan="${1 + Object.keys(values).length}">
${unsafeHTML(desc)}
</td>
</tr>
`;
`;

for (var k in values) {
let v = values[k];
for (const k in values) {
const v = values[k];

yield html`
<tr>
<td><span class="key" style="margin-left: ${(ident+1) * 20}px"><span class="${valueClass}">${k}: ${v}</span></span></td>
<td><span class="comment">#&nbsp;</span></td>
</tr>
`;
}
} else {
yield html`
<tr>
<td>
<span class="key" style="margin-left: ${(ident + 1) * 20}px"><span class="${valueClass}">${k}: ${v}</span></span>
</td>
<td class="comment">#&nbsp;</td>
</tr>
`;
}
} else {
yield html`
<tr>
<td><span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span> <span class="${valueClass}">${value}</span></td>
<td><span class="comment">#&nbsp;</span></td>
<td><span class="comment">${unsafeHTML(desc)}</span></td>
<td>
<span class="${keyClass}" style="margin-left: ${ident * 20}px">${key}:</span>
<span class="${valueClass}">${value}</span>
</td>
<td class="comment">#&nbsp;</td>
<td class="comment">${unsafeHTML(desc)}</td>
</tr>
`;
`;
}

// This definition references another definition
if (definition.$ref) {
yield html`
yield html`
${template(definitions, definition, definition.$ref, ident + 1)}
`;
`;
}

// This definition is an array
if (definition.items && definition.items.$ref) {
yield html`
${template(definitions, definition, definition.items.$ref, ident + 1)}
`;
yield html`
${template(definitions, definition, definition.items.$ref, ident + 1)}
`;
}
}
}
Loading