[Dev] Added Typedoc plugins + README badges (#6400)

* Add copyright in footer

* Customized typedoc configuration + added coverage SVG

* Finally figured out how to slap the SVG onto the docs' readme per branch

* Fixed up config, made final tweaks to SVG length and renamed script

* Added missing closing bracket to type config declaration

* Fixed title + added GitHub navigation link

* Fixed name typo

* Update README.md

* Moved badges on same line

.github/workflows/github-pages.yml

@@ -23,7 +23,9 @@ jobs:
     timeout-minutes: 10
     runs-on: ubuntu-latest
     env:
-      api-dir: ./
+      docs-dir: ./pokerogue_docs
+      # Only push docs when running on pushes to main/beta
+      DRY_RUN: ${{github.event_name == 'push' && (github.ref_name == 'beta' || github.ref_name == 'main')}}
 
     strategy:
       fail-fast: false
@@ -58,19 +60,18 @@ jobs:
           ref: gh-pages
 
       - name: Install Node.js dependencies
-        working-directory: ${{env.api-dir}}
+        working-directory: ${{env.docs-dir}}
-        run: |
+        run: pnpm i
-          cd pokerogue_docs
-          pnpm i
 
       - name: Generate Typedoc docs
-        working-directory: ${{env.api-dir}}
+        working-directory: ${{env.docs-dir}}
-        run: |
+        env:
-          cd pokerogue_docs
+          REF_NAME: ${{github.ref_name}}
-          pnpm exec typedoc --out /tmp/docs --githubPages false --entryPoints ./src/
+          DRY_RUN: ${{env.DRY_RUN}}
+        run: pnpm typedoc
 
       - name: Commit & Push docs
-        if: github.event_name == 'push' && (github.ref_name == 'beta' || github.ref_name == 'main')
+        if: ${{!env.DRY_RUN}}
         run: |
           cd pokerogue_gh
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -78,6 +79,5 @@ jobs:
           mkdir -p $GITHUB_REF_NAME
           rm -rf $GITHUB_REF_NAME/*
           cp -r /tmp/docs/. $GITHUB_REF_NAME
-          git add $GITHUB_REF_NAME
+          git commit --allow-empty -am "[skip ci] Deploy docs"
-          git commit --allow-empty -m "[skip ci] Deploy docs"
           git push

README.md

@@ -1,5 +1,10 @@
 <picture><img src="./public/images/logo.png" width="300" alt="PokéRogue"></picture>
 
+![Discord Static Badge](https://img.shields.io/badge/Community_Discord-blurple?style=flat&logo=discord&logoSize=auto&labelColor=white&color=5865F2&link=https://discord.gg/pokerogue)
+[![Docs Coverage Static Badge](https://pagefaultgames.github.io/pokerogue/beta/coverage.svg)](https://pagefaultgames.github.io/pokerogue/beta)
+[![Testing Badge](https://github.com/pagefaultgames/pokerogue/actions/workflows/tests.yml/badge.svg)](https://github.com/pagefaultgames/pokerogue/actions/workflows/tests.yml)
+[![License: GNU AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+
 PokéRogue is a browser based Pokémon fangame heavily inspired by the roguelite genre. Battle endlessly while gathering stacking items, exploring many different biomes, fighting trainers, bosses, and more!
 
 # Contributing
@@ -7,7 +12,7 @@ PokéRogue is a browser based Pokémon fangame heavily inspired by the roguelite
 See [CONTRIBUTING.md](./CONTRIBUTING.md), this includes instructions on how to set up the game locally.
 
 # 📝 Credits
->
+
 > If this project contains assets you have produced and you do not see your name, **please** reach out, either [here on GitHub](https://github.com/pagefaultgames/pokerogue/issues/new) or via [Discord](https://discord.gg/pokerogue).
 
 Thank you to all the wonderful people that have contributed to the PokéRogue project! You can find the credits [here](./CREDITS.md).

global.d.ts

@@ -18,3 +18,14 @@ declare global {
     call<T extends AnyFn>(this: T, thisArg: ThisParameterType<T>, ...argArray: Parameters<T>): ReturnType<T>;
   }
 }
+
+// Global augments for `typedoc` to prevent TS from erroring when editing the config JS file
+declare module "typedoc" {
+  export interface TypeDocOptionMap {
+    coverageLabel: string;
+    coverageColor: string;
+    coverageOutputPath: string;
+    coverageOutputType: "svg" | "json" | "all";
+    coverageSvgWidth: number;
+  }
+}

package.json

@@ -19,7 +19,7 @@
     "typecheck": "tsc --noEmit",
     "biome": "biome check --write --changed --no-errors-on-unmatched --diagnostic-level=error",
     "biome-ci": "biome ci --diagnostic-level=error --reporter=github --no-errors-on-unmatched",
-    "docs": "typedoc",
+    "typedoc": "typedoc",
     "depcruise": "depcruise src test",
     "postinstall": "lefthook install; git submodule update --init --recursive",
     "update-version:patch": "pnpm version patch --force --no-git-tag-version",
@@ -42,6 +42,9 @@
     "msw": "^2.10.4",
     "phaser3spectorjs": "^0.0.8",
     "typedoc": "^0.28.8",
+    "typedoc-github-theme": "^0.3.1",
+    "typedoc-plugin-coverage": "^4.0.1",
+    "typedoc-plugin-mdn-links": "^5.0.9",
     "typescript": "^5.8.3",
     "vite": "^7.0.6",
     "vite-tsconfig-paths": "^5.1.4",

pnpm-lock.yaml

@@ -87,6 +87,15 @@ importers:
       typedoc:
         specifier: ^0.28.8
         version: 0.28.8(typescript@5.8.3)
+      typedoc-github-theme:
+        specifier: ^0.3.1
+        version: 0.3.1(typedoc@0.28.8(typescript@5.8.3))
+      typedoc-plugin-coverage:
+        specifier: ^4.0.1
+        version: 4.0.1(typedoc@0.28.8(typescript@5.8.3))
+      typedoc-plugin-mdn-links:
+        specifier: ^5.0.9
+        version: 5.0.9(typedoc@0.28.8(typescript@5.8.3))
       typescript:
         specifier: ^5.8.3
         version: 5.8.3
@@ -1789,6 +1798,23 @@ packages:
     resolution: {integrity: sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==}
     engines: {node: '>=16'}
 
+  typedoc-github-theme@0.3.1:
+    resolution: {integrity: sha512-j6PmkAGmf/MGCzYjQcUH6jS9djPsNl/IoTXooxC+MoeMkBhbmPyKJlpR6Lw12BLoe2OYpYA2J1KMktUJXp/8Sw==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      typedoc: ~0.28.0
+
+  typedoc-plugin-coverage@4.0.1:
+    resolution: {integrity: sha512-P1QBR5GJSfW3fDrpz4Vkd8z8lzWaBYjaHebRLk0u2Uga0oSFlPaqrCyiHzItBXxZX28aMlNlZwrUnsLgUgqA7g==}
+    engines: {node: '>= 18'}
+    peerDependencies:
+      typedoc: 0.28.x
+
+  typedoc-plugin-mdn-links@5.0.9:
+    resolution: {integrity: sha512-kXssRKBhUd0JeHzFmxWVsGWVFR9WXafe70Y8Ed+MYH2Nu2647cqfGQN1OBKgvXpmAT8MTpACmUIQ7GnQnh1/iw==}
+    peerDependencies:
+      typedoc: 0.27.x || 0.28.x
+
   typedoc@0.28.8:
     resolution: {integrity: sha512-16GfLopc8icHfdvqZDqdGBoS2AieIRP2rpf9mU+MgN+gGLyEQvAO0QgOa6NJ5QNmQi0LFrDY9in4F2fUNKgJKA==}
     engines: {node: '>= 18', pnpm: '>= 10'}
@@ -3634,6 +3660,18 @@ snapshots:
 
   type-fest@4.41.0: {}
 
+  typedoc-github-theme@0.3.1(typedoc@0.28.8(typescript@5.8.3)):
+    dependencies:
+      typedoc: 0.28.8(typescript@5.8.3)
+
+  typedoc-plugin-coverage@4.0.1(typedoc@0.28.8(typescript@5.8.3)):
+    dependencies:
+      typedoc: 0.28.8(typescript@5.8.3)
+
+  typedoc-plugin-mdn-links@5.0.9(typedoc@0.28.8(typescript@5.8.3)):
+    dependencies:
+      typedoc: 0.28.8(typescript@5.8.3)
+
   typedoc@0.28.8(typescript@5.8.3):
     dependencies:
       '@gerrit0/mini-shiki': 3.8.1

typedoc-plugins/typedoc-plugin-rename-svg.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+import { PageKind, Renderer } from "typedoc";
+
+/**
+ * @module
+ * Typedoc plugin to run post-processing on the `index.html` file and replace the coverage SVG
+ * for Beta with the newly generated file for the current branch.
+ */
+
+/**
+ * @param {import('typedoc').Application} app
+ */
+export function load(app) {
+  // Don't do anything if no REF_NAME was specified (likely indicating a local docs run)
+  if (!process.env.REF_NAME) {
+    return;
+  }
+  app.renderer.on(Renderer.EVENT_END_PAGE, page => {
+    if (page.pageKind === PageKind.Index && page.contents) {
+      page.contents = page.contents
+        // Replace links to the beta documentation site with the current ref name
+        .replace(
+          /href="(.*pagefaultgames.github.io\/pokerogue\/).*?"/, // formatting
+          `href="$1/${process.env.REF_NAME}"`,
+        )
+        // Replace the link to Beta's coverage SVG with the SVG file for the branch in question.
+        .replace(
+          /img src=".*?coverage.svg/, // formatting
+          `img src="coverage.svg"`,
+        );
+    }
+  });
+}

typedoc.config.js

@@ -0,0 +1,56 @@
+import { globSync } from "node:fs";
+
+/**
+ * @type {Partial<import("typedoc").TypeDocOptions>}
+ */
+const config = {
+  entryPoints: ["./src", "./test/test-utils"],
+  entryPointStrategy: "expand",
+  exclude: ["**/*+.test.ts", "src/polyfills.ts", "src/vite.env.d.ts"],
+  excludeReferences: true, // prevent documenting re-exports
+  requiredToBeDocumented: [
+    "Enum",
+    "EnumMember",
+    "Variable",
+    "Function",
+    "Class",
+    "Interface",
+    "Property",
+    "Method",
+    "Accessor",
+    "TypeAlias",
+  ],
+  highlightLanguages: ["javascript", "json", "jsonc", "json5", "tsx", "typescript", "markdown"],
+  plugin: [
+    "typedoc-github-theme",
+    "typedoc-plugin-coverage",
+    "typedoc-plugin-mdn-links",
+    ...globSync("./typedoc-plugins/**/*.js").map(plugin => "./" + plugin),
+  ],
+  // Avoid emitting docs for branches other than main/beta
+  emit: process.env.DRY_RUN ? "none" : "docs",
+  out: process.env.CI ? "/tmp/docs" : "./typedoc",
+  name: "PokéRogue",
+  readme: "./README.md",
+  coverageLabel: "Documented",
+  coverageSvgWidth: 120, // Increased from 104 baseline due to adding 2 extra letters
+  favicon: "./public/images/logo.png",
+  theme: "typedoc-github-theme",
+  customFooterHtml: "<p>Copyright <strong>Pagefault Games</strong> 2025</p>",
+  customFooterHtmlDisableWrapper: true,
+  navigationLinks: {
+    GitHub: "https://github.com/pagefaultgames/pokerogue",
+  },
+};
+
+// If generating docs for main/beta, check the ref name and add an appropriate navigation header
+if (!process.env.DRY_RUN && process.env.REF_NAME) {
+  const otherRefName = process.env.REF_NAME === "main" ? "beta" : "main";
+  config.navigationLinks = {
+    ...config.navigationLinks,
+    // This will be "Switch to Beta" when on main, and vice versa
+    [`Switch to ${otherRefName.charAt(0).toUpperCase() + otherRefName.slice(1).toLowerCase()}`]: `https://pagefaultgames.github.io/pokerogue/${otherRefName}`,
+  };
+}
+
+export default config;

typedoc.json

@@ -1,7 +0,0 @@
-{
-  "entryPoints": ["./src"],
-  "entryPointStrategy": "expand",
-  "exclude": ["**/*+.test.ts"],
-  "out": "typedoc",
-  "highlightLanguages": ["javascript", "json", "jsonc", "json5", "tsx", "typescript", "markdown"]
-}