Upgrade ember-cli-addon-docs and friends

New versions of ember-cli-addon-docs bring a CSS reset which breaks ember-table tests. Instead of coupling the ember-table test suite to ember-cli-addon-docs CSS, I created a new ember try config for generating docs and removed the dependencies from the normal dev setup. I've documented how to generate the documentation in the README.md, and I believe updated the deployment/release code appropriately. Other changes related to the ember-cli-addon-docs upgrade include: * Add a dependency on ember-data since it no longer brings along the dependency. * Add newlines to account for bugs in ember-cli-addon-docs. See: ember-learn/ember-cli-addon-docs#473 and ember-learn/ember-cli-addon-docs#402 * Add a missing `END-SNIPPET` without which parsing of the snippet was corrupted. * Make an `hbs` template executable without error.
Addepar · Feb 5, 2021 · 7d322c0 · 7d322c0
1 parent 6c7accb
commit 7d322c0
Show file tree

Hide file tree

Showing 8 changed files with 1,093 additions and 4,203 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -46,10 +46,13 @@ jobs:
             ember-lts-2.18,
             ember-lts-3.4,
             ember-lts-3.8,
+            ember-lts-3.12,
             ember-lts-3.16,
+            ember-lts-3.20,
             ember-release,
             ember-beta,
             ember-canary,
+            ember-default-docs
           ]
 
     steps:

diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@ handle over 100,000 rows without any rendering or performance issues.
 Ember Table 3.x supports:
 
 * Ember 2.8 to latest version of Ember.
+* Last two versions of Chrome, Safari, Edge, Firefox on desktop and mobile.
 
 For older platforms, the final release of Ember Table 2.x (2.2.3) supports:
 
@@ -143,20 +144,6 @@ You can also use the `ember-tfoot` component, which has the same API as
   {{/ember-table}}
 ```
 
-## Browser compatibility
-
-This project is written using an EcmaScript 6 javascript syntax.
-Babel doesn't include polyfill by default, so if you want to target legacy browsers (eg. IE11),
-you need to add this to your `ember-cli-build.js`:
-
-```js
-var app = new EmberApp({
-  'ember-cli-babel': {
-    includePolyfill: true,
-  },
-});
-```
-
 ## Migrating from old Ember table
 
 To support smooth migration from old version of Ember table (support only till ember 1.11), we have
@@ -174,8 +161,31 @@ one table at at time. The recommended migration steps are as follows (if you are
 4. Reinstall the latest version of this `ember-table` repo.
 5. You can start using new version of Ember table from now or replacing the old ones.
 
-# Releasing new versions (for maintainers)
+# Notes for maintainers
+
+### Releasing new versions (for maintainers)
 
 We use [`release-it`](https://github.com/release-it/release-it).
 To create a new release, run `yarn run release`. To do a dry-run: `yarn run release --dry-run`.
 The tool will prompt you to select the new release version.
+
+### Generating documentation.
+
+This library is documented using Ember Addon Docs. v0.6.3+ of that library
+bring a CSS reset files into the test suite of Ember Table, meaning many
+tests would be corrupted away from the useragent styles they were written
+against.
+
+Because of this, building the docs requires going through Ember Try. For
+example to run tests asserting the docs build:
+
+```
+ember try:one ember-default-docs"
+```
+
+You might also want to run a command with the addon docs libraries installed,
+for example to create a production build, and you can do so like this:
+
+```
+ember try:one ember-default-docs --- ember build -e production
+```
diff --git a/config/ember-try.js b/config/ember-try.js
@@ -1,3 +1,4 @@
+/* eslint-env node */
 const getChannelURL = require('ember-source-channel-url');
 
 module.exports = function() {
@@ -36,7 +37,6 @@ module.exports = function() {
             devDependencies: {
               'ember-source': null,
               'ember-angle-bracket-invocation-polyfill': null,
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -45,7 +45,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': '~2.12.0',
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -54,7 +53,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': '~2.18.0',
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -63,7 +61,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': '~3.4.0',
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -72,7 +69,14 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': '~3.8.0',
-              'ember-cli-addon-docs': null,
+            },
+          },
+        },
+        {
+          name: 'ember-lts-3.12',
+          npm: {
+            devDependencies: {
+              'ember-source': '~3.12.0',
             },
           },
         },
@@ -81,7 +85,14 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': '~3.16.0',
-              'ember-cli-addon-docs': null,
+            },
+          },
+        },
+        {
+          name: 'ember-lts-3.20',
+          npm: {
+            devDependencies: {
+              'ember-source': '~3.18.0',
             },
           },
         },
@@ -90,7 +101,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': urls[0],
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -99,7 +109,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': urls[1],
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -108,7 +117,6 @@ module.exports = function() {
           npm: {
             devDependencies: {
               'ember-source': urls[2],
-              'ember-cli-addon-docs': null,
             },
           },
         },
@@ -118,6 +126,17 @@ module.exports = function() {
             devDependencies: {},
           },
         },
+        {
+          name: 'ember-default-docs',
+          command: 'ember test --filter="Acceptance \| docs"',
+          npm: {
+            devDependencies: {
+              'ember-data': '~3.24.0',
+              'ember-cli-addon-docs': '^1.0.0',
+              'ember-cli-addon-docs-yuidoc': '^1.0.0',
+            },
+          },
+        },
       ],
     };
   });

diff --git a/package.json b/package.json
@@ -14,7 +14,7 @@
   "repository": "https://github.com/Addepar/ember-table",
   "scripts": {
     "build": "ember build",
-    "docs:deploy": "ember deploy production",
+    "docs:deploy": "ember try:one ember-default-docs --- ember deploy production",
     "lint": "npm-run-all --aggregate-output --continue-on-error --parallel lint:*",
     "lint:files": "ember adde-lint --file-names",
     "lint:js": "ember adde-lint --javascript",
@@ -58,8 +58,6 @@
     "ember-a11y-testing": "^0.5.0",
     "ember-angle-bracket-invocation-polyfill": "^1.3.1",
     "ember-cli": "~3.1.4",
-    "ember-cli-addon-docs": "0.6.13",
-    "ember-cli-addon-docs-yuidoc": "^0.2.1",
     "ember-cli-dependency-checker": "^3.2.0",
     "ember-cli-deploy": "^1.0.2",
     "ember-cli-deploy-build": "^1.1.1",
@@ -80,7 +78,7 @@
     "ember-qunit": "^4.5.1",
     "ember-radio-button": "^1.2.3",
     "ember-resolver": "^5.1.1",
-    "ember-source": "~3.12",
+    "ember-source": "~3.24.0",
     "ember-source-channel-url": "^1.0.1",
     "ember-truth-helpers": "^2.0.0",
     "ember-try": "^1.1.0",
@@ -101,7 +99,6 @@
   },
   "homepage": "https://Addepar.github.io/ember-table",
   "resolutions": {
-    "ember-cli-addon-docs/ember-fetch/whatwg-fetch": "3.3.1",
     "ember-cli-page-object": "1.15.1",
     "prettier": "1.18.2"
   }

diff --git a/tests/dummy/app/pods/docs/guides/header/fixed-columns/controller.js b/tests/dummy/app/pods/docs/guides/header/fixed-columns/controller.js
@@ -62,6 +62,7 @@ export default Controller.extend({
       { name: 'K', valuePath: 'K' },
     ]);
   }),
+  // END-SNIPPET
 
   actions: {
     toggleFixed(column) {

diff --git a/tests/dummy/app/pods/docs/guides/header/scroll-indicators/template.md b/tests/dummy/app/pods/docs/guides/header/scroll-indicators/template.md
@@ -9,6 +9,7 @@ respective direction.
   {{#demo.example name='scroll-indicators'}}
     <div class="demo-container">
       {{! BEGIN-SNIPPET docs-example-scroll-indicators.hbs }}
+
         <EmberTable as |t|>
           <t.head
             @columns={{columns}}
@@ -33,6 +34,7 @@ them when they are present, or at the edges of the table when they are not.
   {{#demo.example name='scroll-indicators-with-fixed'}}
     <div class="demo-container">
       {{! BEGIN-SNIPPET docs-example-scroll-indicators-with-fixed.hbs }}
+
         <EmberTable as |t|>
           <t.head
             @columns={{columnsWithFixed}}
@@ -47,6 +49,7 @@ them when they are present, or at the edges of the table when they are not.
   {{demo.snippet name='docs-example-scroll-indicators-with-fixed.hbs'}}
   {{demo.snippet name='docs-example-scroll-indicators-with-fixed.js' label='component.js'}}
 {{/docs-demo}}
+
 ## Vertical Scroll Indicators with a Header & Footer
 
 Vertical scroll indicators respect both headers and footers, appearing just
@@ -56,6 +59,7 @@ inside any sticky rows at the top or bottom of the table.
   {{#demo.example name='scroll-indicators-with-footer'}}
     <div class="demo-container">
       {{! BEGIN-SNIPPET docs-example-scroll-indicators-with-footer.hbs }}
+
         <EmberTable as |t|>
           <t.head
             @columns={{columnsWithFooter}}

diff --git a/tests/dummy/app/pods/docs/guides/header/sorting/template.md b/tests/dummy/app/pods/docs/guides/header/sorting/template.md
@@ -66,7 +66,11 @@ you want to sort the content of the table asynchronously, you can unset the
 `sortFunction` and handle the async request yourself.
 
 ```hbs
-{{ember-thead sortFunction=null}}
+<EmberTable as |t|>
+  <t.head
+    sortFunction=null
+  />
+</EmberTable>
 ```
 
 ## Disabling Sorting