diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index 46957c02e56..07a20594996 100644 --- a/.github/workflows/github-pages.yml +++ b/.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}} - run: | - cd pokerogue_docs - pnpm i + working-directory: ${{env.docs-dir}} + run: pnpm i - name: Generate Typedoc docs - working-directory: ${{env.api-dir}} - run: | - cd pokerogue_docs - pnpm exec typedoc --out /tmp/docs --githubPages false --entryPoints ./src/ + working-directory: ${{env.docs-dir}} + env: + REF_NAME: ${{github.ref_name}} + 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 -m "[skip ci] Deploy docs" + git commit --allow-empty -am "[skip ci] Deploy docs" git push \ No newline at end of file diff --git a/README.md b/README.md index 1bb8c7772f3..cf70b5d9335 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ PokéRogue +![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). diff --git a/global.d.ts b/global.d.ts index 8b79d966e3c..92a883f40c9 100644 --- a/global.d.ts +++ b/global.d.ts @@ -18,3 +18,14 @@ declare global { call(this: T, thisArg: ThisParameterType, ...argArray: Parameters): ReturnType; } } + +// 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; + } +} diff --git a/package.json b/package.json index 38386c3d964..0620cf6a88c 100644 --- a/package.json +++ b/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", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c3b58a60f48..089689818ac 100644 --- a/pnpm-lock.yaml +++ b/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 diff --git a/typedoc-plugins/typedoc-plugin-rename-svg.js b/typedoc-plugins/typedoc-plugin-rename-svg.js new file mode 100644 index 00000000000..5fda4ee3c6d --- /dev/null +++ b/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"`, + ); + } + }); +} diff --git a/typedoc.config.js b/typedoc.config.js new file mode 100644 index 00000000000..72c58ee8350 --- /dev/null +++ b/typedoc.config.js @@ -0,0 +1,56 @@ +import { globSync } from "node:fs"; + +/** + * @type {Partial} + */ +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: "

Copyright Pagefault Games 2025

", + 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; diff --git a/typedoc.json b/typedoc.json deleted file mode 100644 index c34e6190c1a..00000000000 --- a/typedoc.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "entryPoints": ["./src"], - "entryPointStrategy": "expand", - "exclude": ["**/*+.test.ts"], - "out": "typedoc", - "highlightLanguages": ["javascript", "json", "jsonc", "json5", "tsx", "typescript", "markdown"] -}