Merge branch 'website-restructuring' into pre-release-v8-examples

pixijs · Jan 17, 2024 · a554482 · a554482
2 parents 2818145 + 83f9bc2
commit a554482
Show file tree

Hide file tree

Showing 47 changed files with 2,507 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -24,3 +24,81 @@ $ npm build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+### Working with Content
+
+Core content on the website is within the working `docs` directory and can have various versions that were snapshot and copied over into the `versioned_docs` directory.
+
+Core content consists of:
+- Guides
+- Examples
+- Tutorials
+
+#### Guides
+
+These are static markdown pages that can be added and edited directly within the `docs/guides` directory.
+
+#### Examples
+
+These are markdown compilations of the JS files on the `src/examples` directory. They are also versioned to match the versions of the docs snapshots. If the exact version of the example is not found, it will fallback to the best-matched most recent version of the examples. be Only the `docs/examples/index.md` entry point can be altered, but the examples themselves should be worked on from within the `src/examples/{version}` directories. Once updated, the command below can be called to generate out the markdown compilations of the examples.
+
+```
+$ npm run generate-example-docs
+```
+
+This command will trigger example markdowns generation on all of the docs directories altogether, both the working docs directory and the versioned docs directories.
+
+__Note__: The examples within the docs version active on the website will be shown on the drop-down menu on the Playground page to serve as starting points for users to explore PixiJS features to their heart's content
+
+#### Tutorials
+
+These also markdown compilations of groups of files on the `src/tutorials` directory. Each tutorial group consists of a number of steps where each step contains a JS code file accompanied by an instruction markdown file, and a separate completed JS code file if there is a next step to proceed towards. These completed code can be toggled on/off from the instruction card of the corresponded step. Like the examples, these are also versioned to match the versions of the docs snapshots and will fallback to the best-matched most recent version of the tutorials if the exact version is not found. Only the `docs/tutorials/index.md` entry point can be altered, but the tutorial groups themselves should be worked on from within the `src/tutorial/{version}` directories. Once updated, the command below can be called to generate out the markdown compilations of the tutorial groups.
+
+```
+$ npm run generate-tutorial-docs
+```
+
+This command will trigger tutorial markdowns generation on all of the docs directories altogether, both the working docs directory and the versioned docs directories.
+
+#### Workflow
+
+```
+$ npm start
+```
+
+The local development command will also trigger the `generate-content` command which, in turns, calls the `generate-example-docs` script and `generate-tutorial-docs` script respectively. Since the compiled markdown pages contain dynamic components, changes within the examples source or the tutorials source will be reflected on hot reloads.
+
+However, when adding or removing tutorials or examples, please make sure to re-do `npm start` or run `generate-content` manually to keep the markdown pages of these content up-to-date.
+
+#### Versioning
+
+Docs versioning is native to Docusaurus, but to make it easier to manage it is coupled with the PixiJS version. A `pixi-version.json` is required on the working docs directory to create a versioned snapshot of the docs. This can be generated and altered using the following command:
+
+```
+$ npm run generate-pixi-version-config
+```
+
+The command will retrieve the up-to-date versions and tags from PixiJS and display out as an interactive list for selection.
+
+Once satisfied with the state of the working docs and wanting to create a snapshot to make way for another upcoming version, the following command can be called:
+
+```
+$ npm run create-docs-version-snapshot
+```
+
+This will copy everything from the working docs into its own directory within the `versioned_docs` directory and named correspondingly to the version number from the encapsulated `pixi-version.json`, if chosen to be created as a specific version snapshot. If chosen to be snapshot as a generic version then the version key will be simplified to `{major}.x` (eg. `7.x`). Generic version snapshot is recommended over the specific one for maintaining major docs, but for a major version where multiple versions of docs are needed then the ability to create specific version snapshots can be handy. The command will also trigger `update-global-version-config` script which adds the pixi version config to the master `pixi-versions.json` on the root and alter the version config on the `docusaurus.config.js` accordingly. Docusaurus will also add the version to its `versions.json` file on the root.
+
+An existing docs snapshot can be removed using the following command:
+
+```
+$ npm run remove-docs-version-snapshot
+```
+
+Or can have its pixi version config altered to another version using the command:
+
+```
+$ npm run switch-snapshot-pixi-version-config
+```
+
+where both come with an interactive list of all the snapshots for selection to be actioned on accordingly.
+
+The `update-pixi-version-configs` script is also called pre-build and pre-deploy to update all the outdated labels or metadata on the `pixi-version.json` config on all the docs directories.
diff --git a/blog/2023-10-03-pixi-v8-beta.md b/blog/2023-10-03-pixi-v8-beta.md
@@ -71,8 +71,8 @@ The net effect of these improvements? A decent performance leap across varying u
 These benchmark numbers are based on this Bunnymark test that you can try yourself!
 
 - [v7 Bunnymark](https://goodboydigital.github.io/pixi-bunnymark/dist/?version=v7&count=100000&renderer=webgpu)
-- [v8 Bunnmark - WebGPU](https://goodboydigital.github.io/pixi-bunnymark/dist/?version=v8&count=100000&renderer=webgpu)
-- [v8 Bunnmark - WebGL](https://goodboydigital.github.io/pixi-bunnymark/dist/?version=v8&count=100000&renderer=webgl)
+- [v8 Bunnymark - WebGPU](https://goodboydigital.github.io/pixi-bunnymark/dist/?version=v8&count=100000&renderer=webgpu)
+- [v8 Bunnymark - WebGL](https://goodboydigital.github.io/pixi-bunnymark/dist/?version=v8&count=100000&renderer=webgl)
 - [Repo](https://github.com/GoodBoyDigital/pixi-bunnymark)
 
 

diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -10,5 +10,5 @@ If you're new to PixiJS, we suggest you start with the Basics and read through t
 
 As you explore the guides, you may find these resources valuable:
 
-* [PixiJS API documentation](https://pixijs.download/release/docs)
+* [PixiJS API documentation](https://pixijs.download/release/docs/index.html)
 * [PixiJS Github repo](https://github.com/pixijs/pixijs)
diff --git a/docs/pixi-version.json b/docs/pixi-version.json
@@ -1,10 +1,10 @@
 {
-  "versionLabel": "prerelease-v8",
-  "version": "8.0.0-rc.3",
-  "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc.3",
-  "build": "https://pixijs.download/v8.0.0-rc.3/pixi.min.js",
-  "docs": "https://pixijs.download/v8.0.0-rc.3/docs/index.html",
-  "npm": "8.0.0-rc.3",
+  "versionLabel": "v8.x",
+  "version": "8.0.0-rc.4",
+  "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc.4",
+  "build": "https://pixijs.download/v8.0.0-rc.4/pixi.min.js",
+  "docs": "https://pixijs.download/v8.0.0-rc.4/docs/index.html",
+  "npm": "8.0.0-rc.4",
   "prerelease": true,
   "latest": false
 }
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -43,13 +43,17 @@ const config = {
                     editUrl: 'https://github.com/pixijs/pixijs.com/tree/main/',
                     routeBasePath: '/',
                     versions: {
-                        '7.3.2': {
+                        '7.x': {
                             label: 'v7.x (Latest)',
-                            path: '7.3.2',
+                            path: '7.x',
+                            banner: 'none',
+                            badge: false,
                         },
 
                         current: {
-                            label: 'prerelease-v8',
+                            label: 'v8.x',
+                            banner: 'none',
+                            badge: false,
                         },
                     },
                 },

diff --git a/legacy-pixi-versions.json b/legacy-pixi-versions.json
@@ -0,0 +1,50 @@
+[
+  {
+    "versionLabel": "v7.2.x",
+    "version": "7.2.4",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v7.2.4",
+    "build": "https://pixijs.download/v7.2.4/pixi.min.js",
+    "docs": "https://pixijs.download/v7.2.4/docs/index.html",
+    "npm": "7.2.4"
+  },
+  {
+    "versionLabel": "v7.1.x",
+    "version": "7.1.4",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v7.1.4",
+    "build": "https://pixijs.download/v7.1.4/pixi.min.js",
+    "docs": "https://pixijs.download/v7.1.4/docs/index.html",
+    "npm": "7.1.4"
+  },
+  {
+    "versionLabel": "v7.0.x",
+    "version": "7.0.5",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v7.0.5",
+    "build": "https://pixijs.download/v7.0.5/pixi.min.js",
+    "docs": "https://pixijs.download/v7.0.5/docs/index.html",
+    "npm": "7.0.5"
+  },
+  {
+    "versionLabel": "v6.x",
+    "version": "6.5.10",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v6.5.10",
+    "build": "https://pixijs.download/v6.5.10/pixi.min.js",
+    "docs": "https://pixijs.download/v6.5.10/docs/index.html",
+    "npm": "6.5.10"
+  },
+  {
+    "versionLabel": "v5.x",
+    "version": "5.3.12",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v5.3.12",
+    "build": "https://pixijs.download/v5.3.12/pixi.min.js",
+    "docs": "https://pixijs.download/v5.3.12/docs/index.html",
+    "npm": "5.3.12"
+  },
+  {
+    "versionLabel": "v4.x",
+    "version": "4.8.9",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v4.8.9",
+    "build": "https://pixijs.download/v4.8.9/pixi.min.js",
+    "docs": "https://pixijs.download/v4.8.9/docs/index.html",
+    "npm": "4.8.9"
+  }
+]
diff --git a/pixi-dev-versions.json b/pixi-dev-versions.json
@@ -0,0 +1,18 @@
+[
+    {
+        "versionLabel": "dev",
+        "version": "dev",
+        "releaseNotes": "https://github.com/pixijs/pixijs/releases",
+        "build": "https://pixijs.download/dev/pixi.min.js",
+        "docs": "https://pixijs.download/dev/docs/index.html",
+        "dev": true
+    },
+    {
+        "versionLabel": "next-v8",
+        "version": "next-v8",
+        "releaseNotes": "https://github.com/pixijs/pixijs/releases",
+        "build": "https://pixijs.download/next-v8/pixi.min.js",
+        "docs": "https://pixijs.download/next-v8/docs/index.html",
+        "dev": true
+    }
+]
diff --git a/pixi-versions.json b/pixi-versions.json
@@ -1,22 +1,22 @@
 [
   {
     "versionLabel": "v7.x (Latest)",
-    "version": "7.3.2",
-    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v7.3.2",
-    "build": "https://pixijs.download/v7.3.2/pixi.min.js",
-    "docs": "https://pixijs.download/v7.3.2/docs/index.html",
-    "npm": "7.3.2",
+    "version": "7.3.3",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v7.3.3",
+    "build": "https://pixijs.download/v7.3.3/pixi.min.js",
+    "docs": "https://pixijs.download/v7.3.3/docs/index.html",
+    "npm": "7.3.3",
     "prerelease": false,
     "latest": true,
     "isCurrent": false
   },
   {
-    "versionLabel": "prerelease-v8",
-    "version": "8.0.0-rc.3",
-    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc.3",
-    "build": "https://pixijs.download/v8.0.0-rc.3/pixi.min.js",
-    "docs": "https://pixijs.download/v8.0.0-rc.3/docs/index.html",
-    "npm": "8.0.0-rc.3",
+    "versionLabel": "v8.x",
+    "version": "8.0.0-rc.4",
+    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc.4",
+    "build": "https://pixijs.download/v8.0.0-rc.4/pixi.min.js",
+    "docs": "https://pixijs.download/v8.0.0-rc.4/docs/index.html",
+    "npm": "8.0.0-rc.4",
     "prerelease": true,
     "latest": false,
     "isCurrent": true

diff --git a/scripts/create-docs-version-snapshot.js b/scripts/create-docs-version-snapshot.js
@@ -1,49 +1,75 @@
 const { unlinkSync, existsSync, readFileSync } = require('fs');
 const shell = require('shelljs');
 const { join, resolve } = require('path');
+const inquirer = require('inquirer');
 
 const docsDir = './docs';
 const versionFile = join(docsDir, 'pixi-version.json');
 
+function getGenericVersion(version)
+{
+    return version.replace(/(\d+)(\.\d+)?(\.\d+)?(-.*)?/, '$1.x');
+}
+
 console.log('Creating a version snapshot of the docs...');
 
 try
 {
-    // Generate pixi-version.json if it doesn't exist
-    if (!existsSync(versionFile))
+    (async () =>
     {
-        console.log(
-            'Aborting snapshot - Pixi version config not found on the working docs.',
-            'please generate one first using \'npm run generate-pixi-version-config\'',
-        );
+        // Generate pixi-version.json if it doesn't exist
+        if (!existsSync(versionFile))
+        {
+            console.log(
+                'Aborting snapshot - Pixi version config not found on the working docs.',
+                'please generate one first using \'npm run generate-pixi-version-config\'',
+            );
 
-        shell.exit(0);
-    }
+            shell.exit(0);
+        }
 
-    // Read pixi-version.json to get the version
-    const version = JSON.parse(readFileSync(versionFile, 'utf8')).version;
+        // Read pixi-version.json to get the version
+        const version = JSON.parse(readFileSync(versionFile, 'utf8')).version;
 
-    // Check if a snapshot of the version already exists
-    if (existsSync(join(docsDir, `versioned_docs/version-${version}`)))
-    {
-        console.log(
-            `Aborting snapshot - Snapshot for version ${version} already exists.`,
-            `Please do 'npm run overwrite-docs-version-snapshot' instead to`,
-            `overwrite an existing snapshot with the current docs content.`,
-        );
-        shell.exit(0);
-    }
+        // Grab the generic version as an option for user to choose as well
+        const genericVersion = getGenericVersion(version);
+
+        // Let the user choose between snapshotting the specific version or the generic version
+        const choice = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'selected',
+                message: 'Would you like to snapshot as a generic or a specific version?',
+                choices: [genericVersion, version],
+                default: genericVersion,
+                loop: false,
+            },
+        ]);
+
+        const selectedVersion = choice.selected;
 
-    // Run docusaurus version with the version
-    shell.exec(`npm run docusaurus docs:version ${version}`);
+        // Check if a snapshot of the version already exists
+        if (existsSync(join(docsDir, `versioned_docs/version-${selectedVersion}`)))
+        {
+            console.log(
+                `Aborting snapshot - Snapshot for version ${selectedVersion} already exists.`,
+                `Please do 'npm run overwrite-docs-version-snapshot' instead to`,
+                `overwrite an existing snapshot with the current docs content.`,
+            );
+            shell.exit(0);
+        }
 
-    // Then update the global version configs accordingly
-    shell.exec('npm run update-global-version-configs');
+        // Run docusaurus version with the version
+        shell.exec(`npm run docusaurus docs:version ${selectedVersion}`);
 
-    console.log(
-        `** pixi version config on the working docs currently conflicts with the recent snapshot's.`,
-        `Please do 'npm run generate-pixi-version-config' to resolve this accordingly **`,
-    );
+        // Then update the global version configs accordingly
+        shell.exec('npm run update-global-version-configs');
+
+        console.log(
+            `** pixi version config on the working docs currently conflicts with the recent snapshot's.`,
+            `Please do 'npm run generate-pixi-version-config' to resolve this accordingly **`,
+        );
+    })();
 }
 catch (error)
 {

diff --git a/scripts/generate-pixi-version-config.js b/scripts/generate-pixi-version-config.js
@@ -172,6 +172,19 @@ async function doesVersionConfigExist(version)
         versionLabel = `v${version}`;
     }
 
+    // Prompt the user to confirm or customize the version label
+    versionLabel = (
+        await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'versionLabel',
+                message: 'Confirm or customize the version label:',
+                default: versionLabel,
+                validate: (input) => input.trim().length > 0,
+            },
+        ])
+    ).versionLabel;
+
     config = {
         versionLabel,
         version,

diff --git a/scripts/legacy/write-versions.js b/scripts/legacy/write-versions.js
@@ -109,7 +109,7 @@ const { compareVersions } = require('compare-versions');
         version: 'dev',
         releaseNotes: 'https://github.com/pixijs/pixijs/releases',
         build: 'https://pixijs.download/dev/pixi.min.js',
-        docs: 'https://pixijs.download/release/docs',
+        docs: 'https://pixijs.download/release/docs/index.html',
         dev: true,
         npm: codeSandboxBaseUrl,
     });