Merge pull request #605 from processing/dev-2.0-docs

Add script to preview a custom branch

Author: davepagurek

.gitignore

@@ -23,4 +23,7 @@ pnpm-debug.log*
 temp/*
 in/
 out/
-translator/
+translator/
+
+# Don't commit custom dev builds
+public/p5.min.js

docs/scripts.md

@@ -4,6 +4,23 @@ This repo includes a few scripts to pull content from external sources, primaril
 
 They are all runnable via npm scripts.
 
+## Testing the docs of your fork
+
+If you are contributing a change to the main p5.js repo that affects documentation, you will want to preview how your changes will look on the website. To do so, make sure you have committed your changes to a branch of your fork of p5.js.
+
+Then, in the p5.js-website repo, run the following command, using the URL of your fork  of p5 before the `#`, and the name of your branch after the `#`:
+
+```sh
+npm run custom:dev https://github.com/yourUsername/p5.js.git#yourBranch
+```
+
+This will build the reference from your branch and start a development preview of the website. A URL will be logged in the console that you can go to in your browser to test out your changes.
+
+When you're done, you can run this command to reset your changes:
+```sh
+npm run custom:cleanup
+```
+
 ## After a p5.js release
 
 To update the content on the p5.js website following a new release of p5.js, you should run all of these commands to pull in the latest content. **Be sure to run the search indices script last as it depends on the results of the other scripts to be accurate.**

package.json

@@ -15,7 +15,9 @@
     "build:contributors": "tsx ./src/scripts/builders/people.ts",
     "build:reference": "tsx ./src/scripts/builders/reference.ts",
     "build:search": "tsx ./src/scripts/builders/search.ts",
-    "build:p5-version": "tsx ./src/scripts/p5-version.ts"
+    "build:p5-version": "tsx ./src/scripts/p5-version.ts",
+    "custom:dev": "tsx ./src/scripts/branchTest.ts",
+    "custom:cleanup": "tsx ./src/scripts/resetBranchTest.ts"
   },
   "dependencies": {
     "@astrojs/check": "^0.5.5",

src/content/reference/config.ts

@@ -26,8 +26,8 @@ export const categories = [
 const paramSchema = z.object({
   name: z.string(),
   description: z.string(),
-  type: z.string(),
-  optional: z.boolean().optional(),
+  type: z.string().optional(),
+  optional: z.coerce.boolean().optional(),
 });
 
 const returnSchema = z.object({
@@ -41,15 +41,15 @@ const exampleSchema = z.string();
  * Method schema for methods associated with a class in the Reference collection.
  */
 const methodSchema = z.object({
-  description: z.string(),
+  description: z.string().optional(),
   path: z.string(),
 });
 
 /**
  * Property schema for properties associated with a class in the Reference collection.
  */
 const propertySchema = z.object({
-  description: z.string(),
+  description: z.string().optional(),
   path: z.string(),
 });
 
@@ -78,6 +78,7 @@ export const referenceSchema = z.object({
   properties: z.record(propertySchema).optional(),
   isConstructor: z
     .boolean()
+    .or(z.number().transform((n: number) => !!n))
     .or(z.literal("true").transform(() => true))
     .or(z.literal("false").transform(() => false))
     .optional(),

src/globals/globals.ts

@@ -14,7 +14,8 @@ export const sketchesPerPage = 12 as const;
 export const eventsPerPage = 12 as const;
 
 export const cdnLibraryUrl =
-  `https://cdn.jsdelivr.net/npm/p5@${p5Version}/lib/p5.min.js` as const;
+  `/p5.min.js` as const;
+  // `https://cdn.jsdelivr.net/npm/p5@${p5Version}/lib/p5.min.js` as const;
 export const fullDownloadUrl =
   `https://github.com/processing/p5.js/releases/download/v${p5Version}/p5.zip` as const;
 export const libraryDownloadUrl =

src/scripts/branchTest.ts

@@ -0,0 +1,32 @@
+import { execSync } from "child_process";
+import { existsSync, rmSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const url = process.argv[2];
+const match = /^(.+)#(.+)$/.exec(url);
+if (!match) {
+  console.error(
+    `Please pass a git URL followed by a # and then a branch name, tag, or commit as the parameter to this script, e.g. https://github.com/processing/p5.js.git#main`,
+  );
+  process.exit(1);
+}
+
+const repoUrl = match[1];
+const branch = match[2];
+
+const env = `P5_LIBRARY_PATH='/p5.min.js' P5_REPO_URL='${repoUrl}' P5_BRANCH='${branch}'`;
+
+// First delete the existing cloned p5 to make sure we clone fresh
+const parsedP5Path = path.join(__dirname, "./parsers/in/p5.js/");
+if (existsSync(parsedP5Path)) {
+  rmSync(parsedP5Path, { recursive: true });
+}
+
+// Build the reference using the specified environment
+execSync(`${env} npm run build:reference`, { stdio: "inherit" });
+
+// Run a dev server
+execSync(`${env} npm run dev`, { stdio: "inherit" });

src/scripts/builders/contribute.ts

@@ -19,6 +19,7 @@ import matter from "gray-matter";
 import { compile } from "@mdx-js/mdx";
 import isAbsoluteUrl from "is-absolute-url";
 import { nonDefaultSupportedLocales } from "@/src/i18n/const";
+import { p5Version } from "@/src/globals/p5-version";
 
 /* Repo to pull the contributor documentation from */
 const docsRepoUrl = "https://github.com/processing/p5.js.git";
@@ -258,7 +259,7 @@ const moveContentDirectory = async (
 const buildContributorDocs = async () => {
   console.log("Building contributor docs...");
 
-  await cloneLibraryRepo(clonedRepoPath, docsRepoUrl);
+  await cloneLibraryRepo(clonedRepoPath, docsRepoUrl, p5Version);
 
   // Clean out previous files
   console.log("Cleaning out current content collection...");

src/scripts/builders/people.ts

@@ -7,6 +7,7 @@ import {
 } from "../utils";
 import { readFile } from "fs/promises";
 import yaml from "js-yaml";
+import { p5Version } from "@/src/globals/p5-version";
 
 /* Repo to pull the contributor documentation from */
 const sourceRepoUrl = "https://github.com/processing/p5.js.git";
@@ -24,7 +25,7 @@ const outputDirectory = path.join(
 const run = async () => {
   console.log("Copying people from p5.js website into people collection...");
 
-  await cloneLibraryRepo(clonedRepoPath, sourceRepoUrl);
+  await cloneLibraryRepo(clonedRepoPath, sourceRepoUrl, p5Version);
 
   const contents = await readFile(
     path.join(clonedRepoPath, ".all-contributorsrc"),

src/scripts/parsers/reference.ts

@@ -1,9 +1,10 @@
-import { cloneLibraryRepo, readFile } from "../utils";
+import { cloneLibraryRepo, p5RepoUrl, readFile } from "../utils";
 import fs from "fs/promises";
-import { exec } from "child_process";
+import { exec, execSync } from "child_process";
 import path from "path";
 import { fileURLToPath } from "url";
 import type { ParsedLibraryReference } from "../../../types/parsers.interface";
+import { p5Version } from "@/src/globals/p5-version";
 
 // Derive the directory name (__dirname equivalent) in ES Module scope
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -18,13 +19,23 @@ const yuidocOutputPath = path.join(__dirname, "out")
 export const parseLibraryReference =
   async (): Promise<ParsedLibraryReference | null> => {
     // Clone p5.js
-    await cloneLibraryRepo(localPath);
-    // TODO(dave): let this happen via `npm run docs` in the p5 repo once we
-    // merge the 2.0 branch
-    await saveYuidocOutput('p5.js', 'data-p5', {
-      flags: `--config ${path.join(__dirname, '../../../yuidoc.json')}`,
-      inputPath: './src',
-    });
+    await cloneLibraryRepo(
+      localPath,
+      process.env.P5_REPO_URL || p5RepoUrl,
+      process.env.P5_BRANCH || p5Version,
+      { shouldFixAbsolutePathInPreprocessor: false },
+    );
+
+    // Install dependencies and build docs in the p5 repo
+    await createP5Docs('p5.js', 'data-p5')
+
+    // If we're using a custom build of p5 instead of a public release, create
+    // a build and copy it to the specified path
+    if (process.env.P5_LIBRARY_PATH) {
+      await createP5Build('p5.js', '../../../public' + process.env.P5_LIBRARY_PATH)
+    }
+
+    // Copy the reference output so we can process it
     const p5Data = await getYuidocOutput('data-p5');
     if (!p5Data) throw new Error('Error generating p5 reference data!');
 
@@ -128,6 +139,31 @@ export const saveYuidocOutput = async (
   }
 };
 
+export const createP5Docs = async (inDirName: string, outDirName: string) => {
+  execSync('npm install', {
+    cwd: path.join(__dirname, 'in', inDirName),
+  })
+  execSync('npm run docs', {
+    cwd: path.join(__dirname, 'in', inDirName),
+  })
+  const outputFilePath = path.join(yuidocOutputPath, outDirName);
+  await fs.mkdir(outputFilePath, { recursive: true })
+  await fs.cp(
+    path.join(__dirname, 'in', inDirName, 'docs', 'reference', 'data.json'),
+    path.join(outputFilePath, 'data.json'),
+  )
+}
+
+export const createP5Build = async (inDirName: string, outPath: string) => {
+  execSync('npm run build', {
+    cwd: path.join(__dirname, 'in', inDirName)
+  })
+  await fs.cp(
+    path.join(__dirname, 'in', inDirName, 'lib', 'p5.min.js'),
+    path.join(__dirname, outPath),
+  )
+}
+
 export async function combineYuidocData(
   inputData: ParsedLibraryReference[],
   outDirName: string

src/scripts/resetBranchTest.ts

@@ -0,0 +1,22 @@
+import { fileURLToPath } from "url";
+import path from "path";
+import { existsSync, rmSync } from "fs";
+import simpleGit from "simple-git";
+
+async function main() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+  const referencePath = path.join(__dirname, '../content/reference/');
+  const dataPath = path.join(__dirname, '../../public/reference/data.json')
+  rmSync(referencePath, { recursive: true });
+
+  const git = simpleGit();
+  await git.checkout('HEAD', [referencePath, dataPath]);
+
+  const p5BuildPath = path.join(__dirname, '../../public/p5.min.js');
+  if (existsSync(p5BuildPath)) {
+    rmSync(p5BuildPath);
+  }
+}
+
+main().then(() => process.exit(0))