Generate deprecations tables from Sass API

sass · May 21, 2024 · c8b1d3f · c8b1d3f
1 parent 008890e
commit c8b1d3f
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 76 deletions.
diff --git a/source/_includes/deprecations.liquid b/source/_includes/deprecations.liquid
@@ -0,0 +1,33 @@
+{%- if deprecations.size == 0 -%}
+<p>There are no {{status}} deprecations in the latest version of Dart Sass.</p>
+{%- else -%}
+<p>The following deprecation IDs can be passed to this option:</p>
+
+<table style="width:100%">
+<thead>
+  <tr style="text-align: left">
+    <th>ID</th>
+    {%- if status == "active" -%}<th>Version</th>{%- endif -%}
+    <th>Description</th>
+  </tr>
+</thead>
+<tbody>
+{%- for deprecation in deprecations -%}
+  <tr>
+    <td>
+    {%- if deprecation.hasWebpage -%}
+      <a href="/documentation/breaking-changes/{{deprecation.id}}">
+    {%- endif -%}
+    <code>{{deprecation.id}}</code>
+    {%-if deprecation.hasWebpage -%}</a>{%- endif -%}
+    </td>
+    {%- if status == "active" -%}
+      <td>{{deprecation.deprecatedIn}}</td>
+    {%- endif -%}
+    <td>{{deprecation.description}}</td>
+  </tr>
+{%- endfor -%}
+</tbody>
+</table>
+{%- endif -%}
+
diff --git a/source/documentation/cli/dart-sass.md b/source/documentation/cli/dart-sass.md
@@ -478,79 +478,7 @@ Remove this setting if you need to keep using this feature.
   style.scss 1:9  root stylesheet
 ```
 
-The following deprecation IDs can be passed to this option:
-
-<table style="width:100%">
-<thead>
-  <tr style="text-align: left">
-    <th>ID</th>
-    <th>Version</th>
-    <th>Description</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td><code>call-string</code></td>
-    <td>0.0.0</td>
-    <td>Passing a string directly to <code>meta.call()</code>.</td>
-  </tr>
-  <tr>
-    <td><code>elseif</code></td>
-    <td>1.3.2</td>
-    <td>Using <code>@elseif</code> instead of <code>@else if</code>.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/moz-document"><code>moz-document</code></a></td>
-    <td>1.7.2</td>
-    <td>Using <code>@-moz-document</code> (except for the empty url prefix hack).</td>
-  </tr>
-  <tr>
-    <td><code>new-global</code></td>
-    <td>1.17.2</td>
-    <td>Declaring new variables with <code>!global</code>.</td>
-  </tr>
-  <tr>
-    <td><code>color-module-compat</code></td>
-    <td>1.23.0</td>
-    <td>Using color module functions in place of plain CSS functions.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/slash-div"><code>slash-div</code></a></td>
-    <td>1.33.0</td>
-    <td>Using the <code>/</code> operator for division.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/bogus-combinators"><code>bogus-combinators</code></a></td>
-    <td>1.54.0</td>
-    <td>Leading, trailing, and repeated combinators.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/strict-unary"><code>strict-unary</code></a></td>
-    <td>1.55.0</td>
-    <td>Ambiguous <code>+</code> and <code>-</code> operators.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/function-units"><code>function-units</code></a></td>
-    <td>1.56.0</td>
-    <td>Passing invalid units to built-in functions.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/duplicate-var-flags"><code>duplicate-var-flags</code></a></td>
-    <td>1.62.0</td>
-    <td>Using multiple copies of <code>!global</code> or <code>!default</code> in a single variable declaration.</td>
-  </tr>
-  <tr>
-    <td><a href="/documentation/breaking-changes/abs-percent"><code>abs-percent</code></a></td>
-    <td>1.65.0</td>
-    <td>Passing percentages to the Sass <code>abs()</code> function.</td>
-  </tr>
-  <tr>
-    <td><code>fs-importer-cwd</code></td>
-    <td>1.73.0</td>
-    <td>Using the current working directory as an implicit load path.</td>
-  </tr>
-</tbody>
-</table>
+{% deprecations 'active' %}{% enddeprecations %}
 
 Alternatively, you can pass a Dart Sass version to treat all deprecations that
 were present in that version as errors. For example,
@@ -567,9 +495,6 @@ early, emitting warnings even though the deprecation is not yet active. This
 option can be combined with `--fatal-deprecation` to emit errors instead of
 warnings for a future deprecation.
 
-The only currently available future deprecation type is `import`, as seen
-here:
-
 ```shellsession
 $ sass --future-deprecation=import style.scss style.css
 Deprecation Warning on line 1, column 9 of style.scss:
@@ -581,6 +506,8 @@ Remove the --future-deprecation=import flag to silence this warning for now.
   ╵
 ```
 
+{% deprecations 'future' %}{% enddeprecations %}
+
 #### `--silence-deprecation`
 
 {% compatibility 'dart: "1.74.0"' %}{% endcompatibility %}

diff --git a/source/helpers/components/deprecations.ts b/source/helpers/components/deprecations.ts
@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import sass from 'sass';
+
+import {liquidEngine} from '../engines';
+
+/**
+ * Renders a table of deprecations with the given status.
+ */
+export default async function deprecations(
+  _: string,
+  status: 'active' | 'future'
+) {
+  const deprecations = [];
+  for (const [id, deprecation] of Object.entries(sass.deprecations)) {
+    if (deprecation.status === status) {
+      deprecations.push({
+        id: id,
+        deprecatedIn: deprecation.deprecatedIn,
+        description: deprecation.description,
+        hasWebpage: fs.existsSync(
+          `source/documentation/breaking-changes/${id}.md`
+        ),
+      });
+    }
+  }
+  return liquidEngine.renderFile('deprecations', {
+    deprecations,
+    status,
+  });
+}
diff --git a/source/helpers/components/index.ts b/source/helpers/components/index.ts
@@ -5,10 +5,12 @@ import {liquidEngine} from '../engines';
 import {stripIndent} from '../type';
 import {default as codeExample} from './codeExample';
 import {compatibility, implStatus} from './compatibility';
+import {default as deprecations} from './deprecations';
 import {getDocTocData, getToc} from './toc';
 
 export {codeExample};
 export {compatibility, implStatus};
+export {deprecations};
 export {getDocTocData, getToc};
 
 /**
@@ -69,6 +71,7 @@ export default function componentsPlugin(eleventyConfig: any) {
   // In the meantime, check the order in the function definition of
   // `compatibility` in `source/helpers/components/compatibility.ts`.
   eleventyConfig.addPairedLiquidShortcode('compatibility', compatibility);
+  eleventyConfig.addPairedLiquidShortcode('deprecations', deprecations);
   eleventyConfig.addPairedLiquidShortcode('funFact', funFact);
   eleventyConfig.addPairedLiquidShortcode('headsUp', headsUp);
 }