Chore: Upgrade Working Docs to use PixiJS v8.0.0-rc.2 and Simplify ex…

…amples and tutorial source versioning (#60)

* Chore: Upgrade Working Docs to use PixiJS v8.0.0-rc.1

* Simplify source versioning for examples and tutorials

* Bump up to v8.0.0-rc.2

* Type fix

* Add ghtoken ignore

* Fix Versioned Links

* Upgrade to RC4

* More Assorted fixes

---------

Co-authored-by: Baz Utsahajit <[email protected]>

.gitignore

@@ -22,4 +22,6 @@ yarn-error.log*
 .idea
 .eslintcache
 
-scripts/pixiVersions.json
+scripts/pixiVersions.json
+
+.ghtoken

docs/guides/basics/getting-started.md

@@ -91,7 +91,7 @@ What we're doing here is adding a JavaScript code block, and in that block creat
 
 When the PIXI.Application class creates the renderer, it builds a Canvas element that it will render *to*.  In order to see what we draw with PixiJS, we need to add this Canvas element to the web page's DOM.  Append the following line to your page's script block:
 
-```JavaScript
+```javascript
   document.body.appendChild(app.view);
 ```
 
@@ -105,7 +105,7 @@ There are a number of ways to draw images in PixiJS, but the simplest is by usin
 
 Before PixiJS can render an image, it needs to be loaded.  Just like in any web page, image loading happens asynchronously.  We'll talk a lot more about resource loading in later guides.  For now, we can use a helper method on the PIXI.Sprite class to handle the image loading for us:
 
-```JavaScript
+```javascript
   // Magically load the PNG asynchronously
   let sprite = PIXI.Sprite.from('sample.png');
 ```
@@ -116,7 +116,7 @@ Before PixiJS can render an image, it needs to be loaded.  Just like in any web
 
 Finally, we need to add our new sprite to the stage.  The stage is simply a [Container](https://pixijs.download/release/docs/PIXI.Container.html) that is the root of the scene graph.  Every child of the stage container will be rendered every frame.  By adding our sprite to the stage, we tell PixiJS's renderer we want to draw it.
 
-```JavaScript
+```javascript
   app.stage.addChild(sprite);
 ```
 

docs/guides/components/containers.md

@@ -10,7 +10,7 @@ However, it's a good idea _not_ to do this.  Standalone Container objects are **
 
 So that's the primary use for Containers - as groups of renderable objects in a hierarchy.
 
-Check out the [container example code](/examples/basic/container).
+Check out the [container example code](../../examples/basic/container).
 
 ## Masking
 

docs/guides/components/graphics.md

@@ -4,7 +4,7 @@
 
 In this guide, we're going to de-mystify the Graphics object, starting with how to think about what it does.
 
-Check out the [graphics example code](/examples/graphics/simple).
+Check out the [graphics example code](../../examples/graphics/simple).
 
 ## Graphics Is About Building - Not Drawing
 
@@ -83,7 +83,7 @@ Doing so is simple.  Create the object, call the various builder functions to ad
 
 You can also use a Graphics object as a complex mask.  To do so, build your object and primitives as usual.  Next create a PIXI.Container object that will contain the masked content, and set its `mask` property to your Graphics object.  The children of the container will now be clipped to only show through inside the geometry you've created.  This technique works for both WebGL and Canvas-based rendering.
 
-Check out the [masking example code](/examples/graphics/simple).
+Check out the [masking example code](../../examples/graphics/simple).
 
 ## Caveats and Gotchas
 

docs/guides/components/interaction.md

@@ -59,7 +59,7 @@ PixiJS supports the following event types:
 
 Any DisplayObject-derived object (Sprite, Container, etc.) can become interactive simply by setting its `eventMode` property to any of the eventModes listed above. Doing so will cause the object to emit interaction events that can be responded to in order to drive your project's behavior.
 
-Check out the [interaction example code](/examples/events/click).
+Check out the [interaction example code](../../examples/events/click).
 
 To respond to clicks and taps, bind to the events fired on the object, like so:
 

docs/guides/components/sprites.md

@@ -6,7 +6,7 @@ Sprites are the simplest and most common renderable object in PixiJS.  They repr
 
 To create a Sprite, all you need is a Texture (check out the Texture guide).  Load a PNG's URL using the PIXI.Loader class, then call `PIXI.Sprite.from(url)` and you're all set.  As a convenience during prototyping, you can pass a non-loaded URL to `from()` and PixiJS will handle it, but your sprite will "pop in" after it loads if you don't pre-load your textures.
 
-Check out the [sprite example code](/examples/sprite/basic).
+Check out the [sprite example code](../../examples/sprite/basic).
 
 ## Using Sprites
 

docs/guides/components/text.md

@@ -14,7 +14,7 @@ In order to draw text to the screen, you use a [Text](https://pixijs.download/re
 
 So when working with PIXI.Text objects, there are two sets of options - standard display object options like position, rotation, etc that work *after* the text is rasterized internally, and text style options that are used *while* rasterizing.  Because text once rendered is basically just a sprite, there's no need to review the standard options.  Instead, let's focus on how text is styled.
 
-Check out the [text example code](/examples/text/pixi-text).
+Check out the [text example code](../../examples/text/pixi-text).
 
 ## Text Styles
 
@@ -80,7 +80,7 @@ In addition to the standard PIXI.Text approach to adding text to your project, P
 
 The primary advantage of this approach is speed - changing text frequently is much cheaper and rendering each additional piece of text is much faster due to the shared source texture.
 
-Check out the [bitmap text example code](/examples/text/bitmap-text).
+Check out the [bitmap text example code](../../examples/text/bitmap-text).
 
 ## BitmapFont
 

docs/guides/components/textures.md

@@ -72,4 +72,4 @@ RenderTexture: A more advanced (but very powerful!) feature is to build a Textur
 
 Each of these texture sources has caveats and nuances that we can't cover in this guide, but they should give you a feeling for the power of PixiJS's texture system. <!--TODO: link to advanced textures guide-->
 
-Check out the [render texture example code](/examples/textures/render-texture-basic).
+Check out the [render texture example code](../../examples/textures/render-texture-basic).

docs/pixi-version.json

@@ -1,10 +1,10 @@
 {
   "versionLabel": "prerelease-v8",
-  "version": "8.0.0-rc",
-  "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc",
-  "build": "https://pixijs.download/v8.0.0-rc/pixi.min.js",
-  "docs": "https://pixijs.download/v8.0.0-rc/docs/index.html",
-  "npm": "8.0.0-rc",
+  "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",
   "prerelease": true,
   "latest": false
 }

docusaurus.config.js

@@ -46,10 +46,14 @@ const config = {
                         '7.3.2': {
                             label: 'v7.x (Latest)',
                             path: '7.3.2',
+                            banner: 'none',
+                            badge: false,
                         },
 
                         current: {
                             label: 'prerelease-v8',
+                            banner: 'none',
+                            badge: false,
                         },
                     },
                 },

package.json

@@ -97,6 +97,7 @@
         "lint-staged": "^13.2.0",
         "prettier": "^2.8.4",
         "recast": "^0.23.4",
+        "semver": "^7.5.4",
         "typescript": "^4.9.4"
     },
     "engines": {

pixi-versions.json

@@ -12,11 +12,11 @@
   },
   {
     "versionLabel": "prerelease-v8",
-    "version": "8.0.0-rc",
-    "releaseNotes": "https://github.com/pixijs/pixijs/releases/tag/v8.0.0-rc",
-    "build": "https://pixijs.download/v8.0.0-rc/pixi.min.js",
-    "docs": "https://pixijs.download/v8.0.0-rc/docs/index.html",
-    "npm": "8.0.0-rc",
+    "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",
     "prerelease": true,
     "latest": false,
     "isCurrent": true

scripts/generate-example-docs.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const { join, resolve, dirname } = require('path');
-const { mkdirSync, readFileSync, rmSync, writeFileSync } = require('fs');
+const { mkdirSync, readFileSync, rmSync, writeFileSync, readdirSync } = require('fs');
+const { valid, lte, rcompare, prerelease, major, minor, patch } = require('semver');
 const glob = require('glob');
 
 const ROOT = resolve(__dirname, '..');
@@ -21,6 +22,12 @@ async function go()
 {
     // Find all pixi-version.json files
     const versionFiles = glob.sync(`${ROOT}/**/pixi-version.json`);
+    const EXAMPLES_PATH = resolve(ROOT, 'src', 'examples');
+
+    // Read the directories in the examples directory
+    const exampleDirectories = readdirSync(EXAMPLES_PATH, { withFileTypes: true })
+        .filter((dirent) => dirent.isDirectory())
+        .map((dirent) => dirent.name);
 
     // Perform the script on all the directories that they are in
     for (const versionFile of versionFiles)
@@ -29,7 +36,19 @@ async function go()
         const EXAMPLES_MD_PATH = resolve(DOCS_PATH, 'examples');
         const pixiVersion = require(versionFile);
         const VERSION = pixiVersion.version;
-        const EXAMPLES_JS_PATH = resolve(ROOT, 'src', 'examples', `v${VERSION}`);
+        const isPrerelease = prerelease(`v${VERSION}`);
+        const versionToCompare = isPrerelease ? `v${major(VERSION)}.${minor(VERSION)}.${patch(VERSION)}` : `v${VERSION}`;
+
+        // Filter and sort the directories to find the best match
+        const bestMatch = exampleDirectories
+            // eslint-disable-next-line no-loop-func
+            .filter((name) => valid(name) && lte(name, versionToCompare))
+            .sort((a, b) => rcompare(a, b))[0];
+
+        console.log(`Generating examples for v${VERSION} using the ${bestMatch} source`);
+
+        const EXAMPLES_JS_PATH = resolve(EXAMPLES_PATH, bestMatch);
+
         const examplesData = require(`${EXAMPLES_JS_PATH}/examplesData.json`);
 
         const directories = Object.keys(examplesData);

scripts/generate-tutorial-docs.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const { join, resolve, dirname } = require('path');
 const { readdirSync, mkdirSync, readFileSync, rmSync, writeFileSync } = require('fs');
+const { valid, lte, rcompare, prerelease, major, minor, patch } = require('semver');
 const glob = require('glob');
 
 const ROOT = resolve(__dirname, '..');
@@ -21,6 +22,12 @@ async function go()
 {
     // Find all pixi-version.json files
     const versionFiles = glob.sync(`${ROOT}/**/pixi-version.json`);
+    const TUTORIALS_PATH = resolve(ROOT, 'src', 'tutorials');
+
+    // Read the directories in the tutorials directory
+    const tutorialDirectories = readdirSync(TUTORIALS_PATH, { withFileTypes: true })
+        .filter((dirent) => dirent.isDirectory())
+        .map((dirent) => dirent.name);
 
     // Perform the script on all the directories that they are in
     for (const versionFile of versionFiles)
@@ -29,7 +36,19 @@ async function go()
         const TUTORIALS_MD_PATH = resolve(DOCS_PATH, 'tutorials');
         const pixiVersion = require(versionFile);
         const VERSION = pixiVersion.version;
-        const TUTORIALS_JS_PATH = resolve(ROOT, 'src', 'tutorials', `v${VERSION}`);
+        const isPrerelease = prerelease(`v${VERSION}`);
+        const versionToCompare = isPrerelease ? `v${major(VERSION)}.${minor(VERSION)}.${patch(VERSION)}` : `v${VERSION}`;
+
+        // Filter and sort the directories to find the best match
+        const bestMatch = tutorialDirectories
+            // eslint-disable-next-line no-loop-func
+            .filter((name) => valid(name) && lte(name, versionToCompare))
+            .sort((a, b) => rcompare(a, b))[0];
+
+        console.log(`Generating tutorials for v${VERSION} using the ${bestMatch} source`);
+
+        const TUTORIALS_JS_PATH = resolve(TUTORIALS_PATH, bestMatch);
+
         const tutorialsData = require(`${TUTORIALS_JS_PATH}/tutorialsData.json`);
 
         const fileData = tutorialsData.map((tutorialKey) =>

scripts/update-global-version-configs.js

@@ -71,6 +71,19 @@ recast.visit(ast, {
                             );
                         }
 
+                        versionProps.push(
+                            recast.types.builders.property(
+                                'init',
+                                recast.types.builders.identifier('banner'),
+                                recast.types.builders.literal('none'),
+                            ),
+                            recast.types.builders.property(
+                                'init',
+                                recast.types.builders.identifier('badge'),
+                                recast.types.builders.literal(false),
+                            ),
+                        );
+
                         return recast.types.builders.property(
                             'init',
                             recast.types.builders.identifier(version.isCurrent ? 'current' : `'${version.version}'`),

src/components/Homepage/ClosingSection/index.tsx

@@ -37,7 +37,7 @@ export default function ClosingSection(): JSX.Element
                                 anim="short-up-anim"
                                 style={animShortUp(0.3, 0.7)}
                                 label="Get Started"
-                                link="/tutorial"
+                                link="next/tutorials"
                                 outline={true}
                             />
                         </div>

src/components/Homepage/HeroHeader/index.tsx

@@ -16,7 +16,7 @@ export default function HeroHeader(): JSX.Element
                 <div className="buttonRow">
                     <HomeCTA label="Download" link="https://github.com/pixijs/pixijs/releases" />
                     &nbsp;
-                    <HomeCTA label="Get Started" link="/tutorial" white={true} outline={true} />
+                    <HomeCTA label="Get Started" link="next/tutorials" white={true} outline={true} />
                 </div>
             </div>
         </header>

src/examples/index.ts

@@ -1,6 +1,7 @@
 import type { OptionGroup } from '../components/Select';
-import v7x from './v7.3.2/index';
-import v8x from './v8.0.0-rc/index';
+import { lte, major, minor, patch, prerelease, rcompare, valid } from 'semver';
+import v7x from './v7.0.0/index';
+import v8x from './v8.0.0/index';
 
 export type ExampleDataEntry = {
     name: string;
@@ -23,18 +24,35 @@ export type ExamplesDataType = Record<string, CategoryDataType>;
 
 // TODO: Use await import to dynamically load versioned content on demand instead?
 const versions: Record<string, { entries: ExamplesDataType; options: OptionGroup[] }> = {
-    '7.3.2': v7x,
-    '8.0.0-rc': v8x,
+    'v7.0.0': v7x,
+    'v8.0.0': v8x,
 };
 
+function getBestVersion(version: string)
+{
+    const isPrerelease = prerelease(version);
+    const versionToCompare = isPrerelease ? `${major(version)}.${minor(version)}.${patch(version)}` : version;
+
+    // Get the keys of the versions object and filter them to find the best match
+    const bestMatch = Object.keys(versions)
+        .filter((name) => valid(name) && lte(name, versionToCompare))
+        .sort((a, b) => rcompare(a, b))[0];
+
+    // Return the entries and options of the best match
+    return versions[bestMatch];
+}
+
 export function getExampleEntry(version: string, pathString: string): ExampleSourceEntry | undefined
 {
+    const bestVersion = getBestVersion(version);
     const [directory, example] = pathString.split('.');
 
-    return versions[version]?.entries[directory]?.[example];
+    return bestVersion?.entries[directory]?.[example];
 }
 
 export function getExampleOptions(version: string): OptionGroup[]
 {
-    return versions[version]?.options;
+    const bestVersion = getBestVersion(version);
+
+    return bestVersion?.options;
 }