docs: create typedoc theme and plugins for references (#5297)

* update typedoc and its plugins

* refactor existing typedoc configurations

* added new typedoc plugin and themes

* added more customization options

* added more customization options

* refactored doc-utils to a workspace

* fix tsconfig

* update README files

* remove comments

* revert type changes

* remove dependencies no longer needed

* removed modules action

docs-util/packages/scripts/doc-change-release.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { Octokit } from "@octokit/core"
+import fs from "fs"
+import path from "path"
+
+const shouldExpire = process.argv.indexOf("--expire") !== -1
+const octokit = new Octokit({
+  auth: process.env.GH_TOKEN,
+})
+
+async function main() {
+  let announcement = {}
+
+  if (shouldExpire) {
+    //check if the file was last updated 6 days ago
+    try {
+      const commitResponse = await octokit.request(
+        "GET /repos/{owner}/{repo}/commits",
+        {
+          owner: "medusajs",
+          repo: "medusa",
+          path: path.join("www", "apps", "docs", "announcement.json"),
+          per_page: 1,
+        }
+      )
+
+      if (
+        commitResponse.data.length &&
+        commitResponse.data[0].commit.committer?.date &&
+        dateDiffInDays(
+          new Date(commitResponse.data[0].commit.committer.date),
+          new Date()
+        ) < 6
+      ) {
+        console.log("File was edited less than 6 days ago. Expiry canceled.")
+        return
+      }
+    } catch (e) {
+      //continue as if file doesn't exist
+    }
+  } else {
+    //retrieve the latest release
+    const response = await octokit.request(
+      "GET /repos/{owner}/{repo}/releases/latest",
+      {
+        owner: "medusajs",
+        repo: "medusa",
+      }
+    )
+
+    const version = response.data.tag_name
+
+    //add new announcement
+    announcement = {
+      id: response.data.html_url,
+      content: `${version} is out`,
+      isCloseable: true,
+    }
+  }
+
+  //write new config file
+  fs.writeFileSync(
+    path.join(
+      __dirname,
+      "..",
+      "..",
+      "..",
+      "www",
+      "apps",
+      "docs",
+      "announcement.json"
+    ),
+    JSON.stringify(announcement)
+  )
+  console.log(`Announcement Bar has been ${shouldExpire ? "removed" : "added"}`)
+}
+
+const _MS_PER_DAY = 1000 * 60 * 60 * 24
+
+// a and b are javascript Date objects
+function dateDiffInDays(a: Date, b: Date) {
+  // Discard the time and time-zone information.
+  const utc1 = Date.UTC(a.getFullYear(), a.getMonth(), a.getDate())
+  const utc2 = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate())
+
+  return Math.floor((utc2 - utc1) / _MS_PER_DAY)
+}
+
+void main()

docs-util/packages/scripts/freshness-check.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+import { LinearClient } from "@linear/sdk"
+import { Octokit } from "@octokit/core"
+import fs from "fs"
+import path from "path"
+
+const octokit = new Octokit({
+  auth: process.env.GH_TOKEN,
+})
+
+const linearClient = new LinearClient({
+  apiKey: process.env.LINEAR_API_KEY,
+})
+
+const repoPath = path.join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "www",
+  "apps",
+  "docs",
+  "content"
+)
+let freshnessCheckLabelId = ""
+let documentationTeamId = ""
+
+async function scanDirectory(startPath: string) {
+  const files = fs.readdirSync(path.join(startPath), {
+    withFileTypes: true,
+  })
+
+  for (const file of files) {
+    const filePath = path.join(startPath, file.name)
+    if (file.isDirectory()) {
+      //if it's references directory, skip
+      if (file.name !== "references" && file.name !== "upgrade-guides") {
+        await scanDirectory(filePath)
+      }
+      continue
+    }
+
+    //check that the file is a markdown file
+    if (file.name.indexOf(".md") === -1 && file.name.indexOf(".mdx") === -1) {
+      continue
+    }
+
+    //if it is a file, check its commits in GitHub
+    const commitResponse = await octokit.request(
+      "GET /repos/{owner}/{repo}/commits",
+      {
+        owner: "medusajs",
+        repo: "medusa",
+        path: filePath,
+        per_page: 1,
+      }
+    )
+
+    if (
+      !commitResponse.data.length ||
+      !commitResponse.data[0].commit.committer?.date
+    ) {
+      continue
+    }
+
+    const today = new Date()
+    const lastEditedDate = new Date(
+      commitResponse.data[0].commit.committer.date
+    )
+    const monthsSinceEdited = getMonthDifference(lastEditedDate, today)
+
+    if (monthsSinceEdited > 6) {
+      //file was edited more than 6 months ago.
+      //check if there's an issue created for this file since the commit date
+      const existingIssue = await linearClient.issues({
+        filter: {
+          createdAt: {
+            gte: subtractMonths(monthsSinceEdited - 6, today),
+          },
+          title: {
+            containsIgnoreCase: `Freshness check for ${filePath}`,
+          },
+          labels: {
+            some: {
+              id: {
+                eq: freshnessCheckLabelId,
+              },
+            },
+          },
+        },
+        first: 1,
+      })
+
+      if (existingIssue.nodes.length) {
+        //an issue has been created for the past 6 months. Don't create an issue for it.
+        continue
+      }
+
+      console.log(`Creating an issue for ${filePath}...`)
+
+      //there are no issues in the past 6 months. Create an issue
+      await linearClient.issueCreate({
+        teamId: documentationTeamId,
+        title: `Freshness check for ${filePath}`,
+        labelIds: [freshnessCheckLabelId],
+        description: `File \`${filePath}\` was last edited on ${lastEditedDate.toDateString()}.`,
+      })
+    }
+  }
+}
+
+async function main() {
+  //fetch documentation team ID from linear
+  const documentationTeam = await linearClient.teams({
+    filter: {
+      name: {
+        eqIgnoreCase: "Documentation",
+      },
+    },
+    first: 1,
+  })
+
+  if (!documentationTeam.nodes.length) {
+    console.log("Please add Documentation team in Linear first then try again")
+    process.exit(1)
+  }
+
+  documentationTeamId = documentationTeam.nodes[0].id
+
+  //fetch freshness check label ID from linear
+  const freshnessCheckLabel = await linearClient.issueLabels({
+    filter: {
+      name: {
+        eqIgnoreCase: "type: freshness-check",
+      },
+      team: {
+        id: {
+          eq: documentationTeamId,
+        },
+      },
+    },
+  })
+
+  if (!freshnessCheckLabel.nodes.length) {
+    console.log(
+      "Please add freshness check label in Linear under the documentation team first then try again"
+    )
+    process.exit(1)
+  }
+
+  freshnessCheckLabelId = freshnessCheckLabel.nodes[0].id
+
+  await scanDirectory(repoPath)
+}
+
+function getMonthDifference(startDate: Date, endDate: Date) {
+  return (
+    endDate.getMonth() -
+    startDate.getMonth() +
+    12 * (endDate.getFullYear() - startDate.getFullYear())
+  )
+}
+
+function subtractMonths(numOfMonths: number, date = new Date()) {
+  date.setMonth(date.getMonth() - numOfMonths)
+
+  return date
+}
+
+void main()

docs-util/packages/scripts/generate-reference.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import path from "path"
+import fs from "fs"
+import { exec } from "child_process"
+
+const referenceNames = process.argv.slice(2)
+referenceNames.forEach((names) => {
+  const configPathName = path.join(
+    __dirname,
+    "..",
+    "typedoc-config",
+    `${names}.js`
+  )
+
+  // check if the config file exists
+  if (!fs.existsSync(configPathName)) {
+    throw new Error(
+      `Config file for ${names} doesn't exist. Make sure to create it in ${configPathName}`
+    )
+  }
+
+  const typedocProcess = exec(`typedoc --options ${configPathName}`)
+  typedocProcess.stdout?.pipe(process.stdout)
+  typedocProcess.stderr?.pipe(process.stdout)
+})

docs-util/packages/scripts/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "scripts",
+  "private": true,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate:announcement": "ts-node ./doc-change-release.ts",
+    "generate:reference": "ts-node ./generate-reference.ts",
+    "check:freshness": "ts-node ./freshness-check.ts"
+  },
+  "version": "0.0.0",
+  "dependencies": {
+    "@linear/sdk": "^1.22.0",
+    "@octokit/core": "^4.0.5",
+    "ts-node": "^10.9.1",
+    "typedoc": "0.25.1",
+    "typedoc-monorepo-link-types": "^0.0.2",
+    "typedoc-plugin-frontmatter": "*",
+    "typedoc-plugin-markdown": "3.16.0",
+    "typedoc-plugin-markdown-medusa": "*",
+    "typedoc-plugin-merge-modules": "5.1.0",
+    "typedoc-plugin-modules": "*",
+    "typedoc-plugin-reference-excluder": "1.1.3",
+    "typedoc-plugin-rename-defaults": "^0.6.6"
+  }
+}

docs-util/packages/scripts/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["*.ts"]
+}