Add TS support for JSDoc (#2613)

* Start on TS support for JSDoc

* Use better-docs theme for now

* Add ts extensions to imports

* Add multiple NoOp types

* Update imports, fix astro hints

.github/workflows/publish-github-pages.yml

@@ -29,8 +29,8 @@ jobs:
         run: |
           pnpm i
           pnpm build
-      # - name: Build docs
-      #   run: pnpm run docs
+      - name: Build docs
+        run: pnpm run docs
       - name: Publish site and docs
         uses: peaceiris/actions-gh-pages@v3
         with:

.jsdoc.js

@@ -7,17 +7,25 @@ module.exports = {
   },
   source: {
     include: [
-      'package.json',
-      'README.md',
-      './src/shepherd.ts',
-      './src/step.ts',
-      './src/tour.ts'
-    ]
+      './shepherd.js/package.json',
+      './shepherd.js/src/shepherd.ts',
+      './shepherd.js/src/step.ts',
+      './shepherd.js/src/tour.ts'
+    ],
+    includePattern: '\\.(json|js|ts)$'
   },
-  plugins: [
-    'plugins/markdown'
-  ],
+  plugins: ['plugins/markdown', 'node_modules/better-docs/typescript'],
   sourceType: 'module',
+  opts: {
+    destination: './site/docs/',
+    encoding: 'utf8',
+    // Do not include functions marked `@private`
+    private: false,
+    readme: 'README.md',
+    recurse: true,
+    template: './node_modules/better-docs',
+    tutorials: './docs-src/tutorials'
+  },
   templates: {
     referenceTitle: 'Shepherd.js',
     favicon: '/landing/public/favicons/favicon-32x32.png',
@@ -28,15 +36,18 @@ module.exports = {
     collapse: false,
     resources: {
       Demo: 'https://shepherdjs.dev/'
+    },
+    'better-docs': {
+      navLinks: [
+        {
+          label: 'Demo',
+          href: 'https://shepherdjs.dev/'
+        },
+        {
+          label: 'GitHub',
+          href: 'https://github.com/shepherd-pro/shepherd'
+        }
+      ]
     }
-  },
-  opts: {
-    destination: './site/docs/',
-    encoding: 'utf8',
-    // Do not include functions marked `@private`
-    private: false,
-    recurse: true,
-    template: './node_modules/jsdoc-template-ship-shape',
-    tutorials: './docs-src/tutorials'
   }
 };

landing/astro.config.mjs

@@ -3,11 +3,16 @@ import mdx from '@astrojs/mdx';
 import sitemap from '@astrojs/sitemap';
 import tailwind from '@astrojs/tailwind';
 
-import partytown from "@astrojs/partytown";
+import partytown from '@astrojs/partytown';
 
 // https://astro.build/config
 export default defineConfig({
   site: 'https://shepherdjs.dev',
-  integrations: [mdx(), sitemap(), tailwind(), partytown({ config: { forward: ['dataLayer.push'] } }),],
+  integrations: [
+    mdx(),
+    sitemap(),
+    tailwind(),
+    partytown({ config: { forward: ['dataLayer.push'] } })
+  ],
   outDir: '../site'
-});
+});

landing/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@astrojs/check": "^0.3.1",
     "@astrojs/mdx": "^2.0.0",
-    "@astrojs/partytown": "^2.0.3",
+    "@astrojs/partytown": "^2.0.4",
     "@astrojs/rss": "^4.0.1",
     "@astrojs/sitemap": "^3.0.3",
     "@astrojs/tailwind": "^5.0.3",

landing/src/layouts/Base.astro

@@ -1,5 +1,5 @@
 ---
-import BaseHead from '../components/BaseHead.astro';
+import BaseHead from '@components/BaseHead.astro';
 import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
 
 const { overrideTitle = SITE_TITLE, overrideDescription = SITE_DESCRIPTION } =

landing/src/layouts/BlogPost.astro

@@ -1,9 +1,8 @@
 ---
 import type { CollectionEntry } from 'astro:content';
-import Base from './Base.astro';
-import Header from '../components/Header.astro';
-import Footer from '../components/Footer.astro';
-import FormattedDate from '../components/FormattedDate.astro';
+import Base from '@layouts/Base.astro';
+import Header from '@components/Header.astro';
+import Footer from '@components/Footer.astro';
 import { SITE_TITLE } from '../consts';
 
 type Props = CollectionEntry<'blog'>['data'];

landing/src/layouts/MainPage.astro

@@ -174,10 +174,11 @@ const shepherdIncludeCode = `
 </Base>
 
 <!-- Welcome page -->
-<script type="module" is:inline>
+<script>
   'use strict';
 
-  import Shepherd from './node_modules/shepherd.js/dist/shepherd.js';
+  import Shepherd from 'shepherd.js';
+  import type { Tour } from 'shepherd.js/tour';
 
   (function () {
     function init() {
@@ -188,6 +189,7 @@ const shepherdIncludeCode = `
     }
 
     function setupShepherd() {
+      // @ts-expect-error TODO
       var shepherd = new Shepherd.Tour({
         defaultStepOptions: {
           cancelIcon: {
@@ -210,14 +212,14 @@ const shepherdIncludeCode = `
             buttons: [
               {
                 action() {
-                  return this.cancel();
+                  return (this as unknown as Tour).cancel();
                 },
                 secondary: true,
                 text: 'Exit'
               },
               {
                 action() {
-                  return this.next();
+                  return (this as unknown as Tour).next();
                 },
                 text: 'Next'
               }
@@ -244,14 +246,14 @@ const shepherdIncludeCode = `
           buttons: [
             {
               action() {
-                return this.back();
+                return (this as unknown as Tour).back();
               },
               secondary: true,
               text: 'Back'
             },
             {
               action() {
-                return this.next();
+                return (this as unknown as Tour).next();
               },
               text: 'Next'
             }
@@ -270,14 +272,14 @@ const shepherdIncludeCode = `
           buttons: [
             {
               action() {
-                return this.back();
+                return (this as unknown as Tour).back();
               },
               secondary: true,
               text: 'Back'
             },
             {
               action() {
-                return this.next();
+                return (this as unknown as Tour).next();
               },
               text: 'Next'
             }
@@ -294,14 +296,14 @@ const shepherdIncludeCode = `
           buttons: [
             {
               action() {
-                return this.back();
+                return (this as unknown as Tour).back();
               },
               secondary: true,
               text: 'Back'
             },
             {
               action() {
-                return this.next();
+                return (this as unknown as Tour).next();
               },
               text: 'Next'
             }
@@ -319,14 +321,14 @@ const shepherdIncludeCode = `
         buttons: [
           {
             action() {
-              return this.back();
+              return (this as unknown as Tour).back();
             },
             secondary: true,
             text: 'Back'
           },
           {
             action() {
-              return this.next();
+              return (this as unknown as Tour).next();
             },
             text: 'Next'
           }
@@ -344,34 +346,26 @@ const shepherdIncludeCode = `
         buttons: [
           {
             action() {
-              return this.back();
+              return (this as unknown as Tour).back();
             },
             secondary: true,
             text: 'Back'
           },
           {
             action() {
-              return this.next();
+              return (this as unknown as Tour).next();
             },
             text: 'Done'
           }
         ],
         id: 'followup',
-        modalOverlayOpeningPadding: '10'
+        modalOverlayOpeningPadding: 10
       });
       return shepherd;
     }
 
     function ready() {
-      if (
-        document.attachEvent
-          ? document.readyState === 'complete'
-          : document.readyState !== 'loading'
-      ) {
-        init();
-      } else {
-        document.addEventListener('DOMContentLoaded', init);
-      }
+      document.addEventListener('DOMContentLoaded', init);
     }
 
     ready();

landing/src/pages/blog/[...slug].astro

@@ -1,8 +1,7 @@
 ---
 import { type CollectionEntry, getCollection } from 'astro:content';
 import { Image } from 'astro:assets';
-import BlogPost from '../../layouts/BlogPost.astro';
-import FormattedDate from '../../components/FormattedDate.astro';
+import BlogPost from '@layouts/BlogPost.astro';
 
 export async function getStaticPaths() {
   const posts = await getCollection('blog');
@@ -14,7 +13,7 @@ export async function getStaticPaths() {
 type Props = CollectionEntry<'blog'>;
 
 const post = Astro.props;
-const { Content, remarkPluginFrontmatter } = await post.render();
+const { Content } = await post.render();
 ---
 
 <BlogPost {...post.data}>

landing/src/pages/blog/index.astro

@@ -1,10 +1,11 @@
 ---
-import Base from '../../layouts/Base.astro';
-import Header from '../../components/Header.astro';
-import Footer from '../../components/Footer.astro';
-import { SITE_TITLE } from '../../consts';
 import { getCollection } from 'astro:content';
-import FormattedDate from '../../components/FormattedDate.astro';
+
+import Base from '@layouts/Base.astro';
+import Header from '@components/Header.astro';
+import Footer from '@components/Footer.astro';
+import { SITE_TITLE } from '../../consts';
+import FormattedDate from '@components/FormattedDate.astro';
 
 const posts = (await getCollection('blog')).sort(
   (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()

landing/src/pages/demo.astro

@@ -1,5 +1,5 @@
 ---
-import MainPage from '../layouts/MainPage.astro';
+import MainPage from '@layouts/MainPage.astro';
 ---
 
 <MainPage />

landing/src/pages/index.astro

@@ -1,5 +1,5 @@
 ---
-import MainPage from '../layouts/MainPage.astro';
+import MainPage from '@layouts/MainPage.astro';
 ---
 
 <MainPage isHome={true} />

landing/src/pages/pricing.astro

@@ -1,7 +1,7 @@
 ---
-import BaseHead from '../components/BaseHead.astro';
-import Header from '../components/Header.astro';
-import Footer from '../components/Footer.astro';
+import BaseHead from '@components/BaseHead.astro';
+import Header from '@components/Header.astro';
+import Footer from '@components/Footer.astro';
 import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
 ---
 

landing/tsconfig.json

@@ -1,6 +1,12 @@
 {
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
-    "strictNullChecks": true
+    "baseUrl": ".",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@layouts/*": ["src/layouts/*"]
+    },
+    "strictNullChecks": true,
+    "verbatimModuleSyntax": true
   }
-}
+}

package.json

@@ -34,6 +34,7 @@
     "@release-it-plugins/lerna-changelog": "^6.1.0",
     "@release-it-plugins/workspaces": "^4.2.0",
     "autoprefixer": "^10.4.16",
+    "better-docs": "^2.7.3",
     "cypress": "^13.6.2",
     "cypress-plugin-tab": "^1.0.5",
     "del": "^7.1.0",