docs: work on configuration page (#5739)

streetsidesoftware · Jun 12, 2024 · acf59a4 · acf59a4
1 parent 08e8a69
commit acf59a4
Show file tree

Hide file tree

Showing 2 changed files with 3,438 additions and 3,507 deletions.
diff --git a/website/_scripts/extract-properties.mjs b/website/_scripts/extract-properties.mjs
@@ -32,7 +32,7 @@ function schemaEntry(entry, name) {
     if (entry.type === 'object') {
         return schemaObjectEntry(entry, name);
     }
-    return `## ${name}\n**Not Handled:** ${entry.type}\n`;
+    return formatTopLevelType(name, entry);
 }
 
 function schemaObjectEntry(schemaTypeObject, nameOfType) {
@@ -64,15 +64,21 @@ function schemaObjectEntry(schemaTypeObject, nameOfType) {
 
 /**
  * @param {string} name - name of heading
- * @param {string} section - the containing entry name
+ * @param {string} [section] - the containing entry name
+ * @param {string} [text] - optional text to show in the link
  */
-function linkToHeader(name, section) {
+function linkToHeader(name, section, text) {
+    text = text || name;
     const id = toId(section, name);
-    return `[${name}](#${id})`;
+    return `[${text}](#${id})`;
 }
 
+/**
+ * @param {string | undefined} nameOfParentType
+ * @param {string} header
+ */
 function toId(nameOfParentType, header) {
-    return `${nameOfParentType}-${header}`.toLowerCase().replaceAll(/\W/g, '-');
+    return (nameOfParentType ? `${nameOfParentType}-${header}` : header).toLowerCase().replaceAll(/\W/g, '-');
 }
 
 function formatPropertyForOverview(key, entry, section) {
@@ -86,26 +92,40 @@ function formatPropertyToDisplay(key, entry, nameOfParentType) {
 
         #### \`${key}\` {#${toId(nameOfParentType, key)}}
 
-        <dl>
-            <dt>Name</dt>
+        ${padLines(formatTypeEntryBody(entry), '        ')}
+    `);
+}
+
+function formatTopLevelType(key, entry) {
+    return removeLeftPad(`
+
+        ---
+
+        ## ${key} {#${toId('', key)}}
+
+        ${padLines(formatTypeEntryBody(entry), '        ')}
+    `);
+}
+
+function formatTypeEntryBody(entry) {
+    let dlDescription = formatEntryDescription(entry, '');
+    if (dlDescription) {
+        dlDescription = removeLeftPad(`
+            <dt>Description</dt>
             <dd>
-                \`${key}\`
+                ${padLines(dlDescription, '                ')}
             </dd>
-        </dl>
+        `);
+    }
 
+    return removeLeftPad(`
         <dl>
+            ${padLines(dlDescription, '            ')}
             <dt>Type</dt>
             <dd>
                 ${formatEntryType(entry)}
             </dd>
         </dl>
-
-        <dl>
-            <dt>Description</dt>
-            <dd>
-                ${formatEntryDescription(entry, '               ')}
-            </dd>
-        </dl>
     `);
 }
 
@@ -118,20 +138,25 @@ function formatEntryType(entry, addFix = '`') {
     }
 
     if (entry.type === 'array' && entry.items) {
-        return fix(`${formatEntryType(entry.items, '')}[]`);
+        return formatEntryType(entry.items, '`') + fix(`[]`);
     }
     if (entry.type) {
         return fix(entry.type);
     }
     if (entry.$ref) {
-        return fix(entry.$ref.split('/').slice(-1).join(''));
+        return formatReferenceType(entry.$ref, fix);
     }
     if (entry.anyOf) {
         return entry.anyOf.map((entry) => formatEntryType(entry)).join('<br />');
     }
     return fix('Unknown');
 }
 
+function formatReferenceType(ref, fnFix) {
+    const refType = ref.split('/').slice(-1).join('');
+    return linkToHeader(refType, '', fnFix(refType));
+}
+
 function formatDefinitions(schema) {
     return Object.entries(schema.definitions || {})
         .map(([key, entry]) => schemaEntry(entry, key))
@@ -177,18 +202,18 @@ const regExpMatchLink = /\{@link (.*?)\}/g;
 function replaceLinks(markdown) {
     markdown = markdown.replaceAll(regExpMatchLink, (_match, p1) => {
         p1 = p1.trim();
-        const link = (p1 && `[${p1}](#${p1.toLowerCase().replaceAll(/\W/g, '-')})`) || '';
+        const link = (p1 && linkToHeader(p1, '')) || '';
         return link;
     });
     return markdown;
 }
 
 /**
  * @param {string} str - multi-line string to left pad
- * @param {string} padding - the padding to use
+ * @param {string} [padding] - the padding to use
  * @param {string} [firstLinePadding] - optional padding of first line.
  */
-function padLines(str, padding, firstLinePadding = '') {
+function padLines(str, padding = '', firstLinePadding = '') {
     let pad = firstLinePadding;
     const lines = [];
     for (const line of str.split('\n')) {