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

README.md

@@ -39,7 +39,7 @@ These are static markdown pages that can be added and edited directly within the
 
 #### 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. 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.
+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
@@ -51,7 +51,7 @@ __Note__: The examples within the docs version active on the website will be sho
 
 #### 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. 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.
+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
@@ -67,6 +67,8 @@ $ 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:
@@ -83,7 +85,7 @@ Once satisfied with the state of the working docs and wanting to create a snapsh
 $ 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`. 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.
+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:
 

docs/pixi-version.json

@@ -1,5 +1,5 @@
 {
-  "versionLabel": "prerelease-v8",
+  "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",

docusaurus.config.js

@@ -43,15 +43,15 @@ const config = {
                     editUrl: 'https://github.com/pixijs/pixijs.com/tree/main/',
                     routeBasePath: '/',
                     versions: {
-                        '7.3.3': {
+                        '7.x': {
                             label: 'v7.x (Latest)',
-                            path: '7.3.3',
+                            path: '7.x',
                             banner: 'none',
                             badge: false,
                         },
 
                         current: {
-                            label: 'prerelease-v8',
+                            label: 'v8.x',
                             banner: 'none',
                             badge: false,
                         },

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"
+  }
+]

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
+    }
+]

pixi-versions.json

@@ -11,7 +11,7 @@
     "isCurrent": false
   },
   {
-    "versionLabel": "prerelease-v8",
+    "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",

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)
 {

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,

scripts/remove-docs-version-snapshot.js

@@ -6,6 +6,11 @@ const inquirer = require('inquirer');
 
 const ROOT = resolve(__dirname, '..');
 
+function getGenericVersion(version)
+{
+    return version.replace(/(\d+)(\.\d+)?(\.\d+)?(-.*)?/, '$1.x');
+}
+
 // Find all pixi-version.json files in the versioned docs directory
 const versionFiles = glob.sync(`${ROOT}/versioned_docs/**/pixi-version.json`);
 
@@ -50,12 +55,20 @@ console.log('Removing a version snapshot of the docs...');
 
     const config = versions.find((version) => version.versionLabel === choice.selected);
 
+    /**
+     * Use the docusaurus versions config to determine if the snapshot is of a generic version,
+     * so that correct directory and sidebar names can be referred to.
+     */
+    const snapshotVersions = JSON.parse(readFileSync(join(ROOT, 'versions.json'), 'utf8'));
+    const isGenericSnapshot = !snapshotVersions.includes(config.version);
+    const key = isGenericSnapshot ? getGenericVersion(config.version) : config.version;
+
     // 1st Confirmation
     const confirmation = await inquirer.prompt([
         {
             type: 'list',
             name: 'selected',
-            message: `Are you sure you want to remove ${config.versionLabel} (v${config.version}) snapshot?`,
+            message: `Are you sure you want to remove ${config.versionLabel} (v${key}) snapshot?`,
             choices: ['no', 'yes'],
             default: 'no',
             loop: false,
@@ -72,11 +85,11 @@ console.log('Removing a version snapshot of the docs...');
         {
             type: 'input',
             name: 'version',
-            message: `Please type version number '${config.version}' to remove the snapshot?`,
+            message: `Please type version number '${key}' to remove the snapshot?`,
         },
     ]);
 
-    if (input.version !== config.version)
+    if (input.version !== key)
     {
         shell.exit(0);
     }
@@ -86,11 +99,8 @@ console.log('Removing a version snapshot of the docs...');
     // Read versions.json
     const data = readFileSync(join(ROOT, 'versions.json'), 'utf8');
 
-    // Parse the JSON
-    let parsed = JSON.parse(data);
-
     // Remove the selected version
-    parsed = parsed.filter((version) => version !== config.version);
+    const parsed = snapshotVersions.filter((version) => version !== key);
 
     // If there are no versions left, delete versions.json
     if (!parsed.length)
@@ -104,12 +114,12 @@ console.log('Removing a version snapshot of the docs...');
     }
 
     // Delete the versioned directory
-    rmSync(join(ROOT, 'versioned_docs', `version-${config.version}`), { recursive: true, force: true });
+    rmSync(join(ROOT, 'versioned_docs', `version-${key}`), { recursive: true, force: true });
 
     // Delete the versioned sidebars
-    rmSync(join(ROOT, 'versioned_sidebars', `version-${config.version}-sidebars.json`), { recursive: true, force: true });
+    rmSync(join(ROOT, 'versioned_sidebars', `version-${key}-sidebars.json`), { recursive: true, force: true });
 
-    console.log(`Successfully removed ${config.versionLabel} (v${config.version}) snapshot!`);
+    console.log(`Successfully removed ${config.versionLabel} (v${key}) snapshot!`);
 
     // Then update the global version configs accordingly
     shell.exec('npm run update-global-version-configs');