fix: Improve the docs (#3620)

streetsidesoftware · Sep 11, 2024 · 4c4f79c · 4c4f79c
1 parent 5523b78
commit 4c4f79c
Show file tree

Hide file tree

Showing 10 changed files with 5,099 additions and 3,336 deletions.
diff --git a/README.md b/README.md
@@ -442,9 +442,6 @@ Note, the settings in `cspell.json` will override the equivalent cSpell settings
     // Enable / Disable the spell checker.
     "cSpell.enabled": true,
 
-    // Display the spell checker status on the status bar.
-    "cSpell.showStatus": true,
-
     // Words to add to dictionary for a workspace.
     "cSpell.words": [],
 

diff --git a/package.json b/package.json
@@ -2533,7 +2533,7 @@
           },
           "cSpell.language": {
             "default": "en",
-            "markdownDescription": "Current active spelling language.\n\nExample: \"en-GB\" for British English\n\nExample: \"en,nl\" to enable both English and Dutch",
+            "markdownDescription": "Current active spelling language.\n\nExample: `en-GB` for British English\n\nExample: `en,nl` to enable both English and Dutch",
             "scope": "resource",
             "type": "string"
           },
@@ -3271,7 +3271,7 @@
           },
           "cSpell.useCustomDecorations": {
             "default": true,
-            "markdownDescription": "Draw custom decorations on Spelling Issues.",
+            "markdownDescription": "Draw custom decorations on Spelling Issues.\n- `true` - Use custom decorations.\n- `false` - Use the VS Code Diagnostic Collection to render spelling issues.",
             "scope": "application",
             "since": "4.0.0",
             "type": "boolean"
@@ -3896,6 +3896,7 @@
           },
           "cSpell.showStatus": {
             "default": true,
+            "deprecationMessage": "No longer used.",
             "markdownDescription": "Display the spell checker status on the status bar.",
             "scope": "application",
             "type": "boolean"

diff --git a/packages/_server/spell-checker-config.schema.json b/packages/_server/spell-checker-config.schema.json
@@ -2052,8 +2052,8 @@
         },
         "cSpell.language": {
           "default": "en",
-          "description": "Current active spelling language.\n\nExample: \"en-GB\" for British English\n\nExample: \"en,nl\" to enable both English and Dutch",
-          "markdownDescription": "Current active spelling language.\n\nExample: \"en-GB\" for British English\n\nExample: \"en,nl\" to enable both English and Dutch",
+          "description": "Current active spelling language.\n\nExample: `en-GB` for British English\n\nExample: `en,nl` to enable both English and Dutch",
+          "markdownDescription": "Current active spelling language.\n\nExample: `en-GB` for British English\n\nExample: `en,nl` to enable both English and Dutch",
           "scope": "resource",
           "type": "string"
         },
@@ -2883,8 +2883,8 @@
         },
         "cSpell.useCustomDecorations": {
           "default": true,
-          "description": "Draw custom decorations on Spelling Issues.",
-          "markdownDescription": "Draw custom decorations on Spelling Issues.",
+          "description": "Draw custom decorations on Spelling Issues.\n- `true` - Use custom decorations.\n- `false` - Use the VS Code Diagnostic Collection to render spelling issues.",
+          "markdownDescription": "Draw custom decorations on Spelling Issues.\n- `true` - Use custom decorations.\n- `false` - Use the VS Code Diagnostic Collection to render spelling issues.",
           "scope": "application",
           "since": "4.0.0",
           "type": "boolean"
@@ -3584,6 +3584,7 @@
         },
         "cSpell.showStatus": {
           "default": true,
+          "deprecationMessage": "No longer used.",
           "description": "Display the spell checker status on the status bar.",
           "markdownDescription": "Display the spell checker status on the status bar.",
           "scope": "application",

diff --git a/packages/_server/src/config/cspellConfig/AppearanceSettings.mts b/packages/_server/src/config/cspellConfig/AppearanceSettings.mts
@@ -178,6 +178,8 @@ interface Appearance extends Decoration {
 export interface AppearanceSettings extends Appearance {
     /**
      * Draw custom decorations on Spelling Issues.
+     * - `true` - Use custom decorations.
+     * - `false` - Use the VS Code Diagnostic Collection to render spelling issues.
      *
      * @scope application
      * @since 4.0.0

diff --git a/packages/_server/src/config/cspellConfig/CSpellSettingsPackageProperties.mts b/packages/_server/src/config/cspellConfig/CSpellSettingsPackageProperties.mts
@@ -24,9 +24,9 @@ export interface CSpellSettingsPackageProperties extends CSpellSettings {
     /**
      * Current active spelling language.
      *
-     * Example: "en-GB" for British English
+     * Example: `en-GB` for British English
      *
-     * Example: "en,nl" to enable both English and Dutch
+     * Example: `en,nl` to enable both English and Dutch
      * @scope resource
      * @default "en"
      */

diff --git a/packages/_server/src/config/cspellConfig/SpellCheckerSettings.mts b/packages/_server/src/config/cspellConfig/SpellCheckerSettings.mts
@@ -108,6 +108,7 @@ export interface SpellCheckerSettings
      * Display the spell checker status on the status bar.
      * @scope application
      * @default true
+     * @deprecationMessage No longer used.
      */
     showStatus?: boolean;
 

diff --git a/website/_scripts/extract-config.mjs b/website/_scripts/extract-config.mjs
@@ -63,7 +63,7 @@ ${formatSections(configSections)}
         function tocEntry(value) {
             if (!value.title) return '';
             const title = value.title;
-            return `- [${title}](#${title.toLowerCase().replace(/\W+/g, '-')})`;
+            return `- [${title}](${hashRef(title)})`;
         }
 
         return `\n${sections
@@ -88,7 +88,7 @@ function formatSections(sections) {
  */
 function sectionEntry(section) {
     const entries = Object.entries(section.properties || {});
-    entries.sort(([a], [b]) => compare(a, b));
+    entries.sort(compareProperties);
     const activeEntries = entries.filter(([, value]) => !value.deprecationMessage);
 
     return `
@@ -103,6 +103,18 @@ ${configDefinitions(entries)}
 `;
 }
 
+/**
+ * Sort properties by name, with deprecated properties last.
+ * @param {[string, JSONSchema4]} a
+ * @param {[string, JSONSchema4]} b
+ * @returns {number}
+ */
+function compareProperties(a, b) {
+    const dA = a[1].deprecationMessage || a[1].deprecated ? 1 : 0;
+    const dB = b[1].deprecationMessage || b[1].deprecated ? 1 : 0;
+    return dA - dB || compare(a[0], b[0]);
+}
+
 /**
  *
  * @param {[string, JSONSchema4][]} entries
@@ -118,10 +130,7 @@ function configTable(entries) {
         const description =
             value.title || value.description?.replace(/\n/g, '<br>') || value.markdownDescription?.replace(/\n[\s\S]*/g, ' ') || '';
         const scope = value.scope || '';
-        return `| [\`${shorten(key, 60)}\`](#${key.toLowerCase().replace(/\W/g, '')}) | ${scope} | ${shortenLine(
-            description,
-            descriptionWidth,
-        )} |`;
+        return `| [\`${shorten(key, 60)}\`](${hashRef(key)}) | ${scope} | ${shortenLine(description, descriptionWidth)} |`;
     }
 
     return `
@@ -182,24 +191,37 @@ function definition(entry) {
     return `
 #### ${name}
 
+<dl>
+
 ${singleDef('Name', `${name} ${title}`)}
 
 ${singleDef('Type', formatType(value), true)}
 
 ${singleDef('Scope', value.scope || '_- none -_')}
 
-${singleDef('Description', description)}
+${singleDef('Description', fixVSCodeRefs(description))}
 
 ${deprecationMessage}
 
 ${singleDef('Default', defaultValue, true)}
 
 ${since ? singleDef('Since Version', since) : ''}
 
+</dl>
+
 ---
 `;
 }
 
+/**
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function fixVSCodeRefs(markdown) {
+    return markdown.replaceAll(/`#(.*?)#`/g, (match, p1) => `[\`${p1}\`](${hashRef(p1)})`);
+}
+
 /**
  *
  * @param {string} term
@@ -209,8 +231,8 @@ ${since ? singleDef('Since Version', since) : ''}
 function singleDef(term, def, addIgnore = false) {
     const lines = [];
 
-    const defLines = def.replaceAll('`jsonc', '`json5').replace(/\n/g, '\n    ');
-    const termDef = '<dl>\n' + `  <dt>${term}</dt>\n  <dd>\n    ${defLines}\n  </dd>\n</dl>`;
+    const defLines = def.replaceAll('`jsonc', '`json5');
+    const termDef = `<dt>\n${term}\n</dt>\n<dd>\n\n${defLines}\n\n</dd>\n`;
     const termLines = termDef.split('\n').map((line) => line.trimEnd());
 
     lines.push(...termLines);
@@ -245,12 +267,21 @@ function formatDefaultValue(value) {
     const lines = text.split('\n');
     if (lines.length > 1) {
         // console.error('%o', lines);
-        return 'code\n```js\n' + text + '\n```\n';
+        return '\n```json5\n' + text + '\n```\n';
     }
 
     return '_`' + text + '`_';
 }
 
+/**
+ *
+ * @param {string} heading
+ * @returns {string}
+ */
+function hashRef(heading) {
+    return '#' + heading.toLowerCase().replaceAll('.', '').replaceAll(/\W+/g, '-');
+}
+
 /**
  *
  * @param {JSONSchema4 | undefined} def
@@ -307,7 +338,8 @@ function extractEnumDescriptions(def) {
         .join('\n');
 
     return `
-
+| Value | Description |
+| ----- | ----------- |
 ${defs}
 `;
 }

diff --git a/website/_scripts/jsconfig.json b/website/_scripts/jsconfig.json
@@ -0,0 +1,6 @@
+{
+    "compilerOptions": {
+        "module": "NodeNext",
+        "target": "ESNext"
+    }
+}