build: p5.sound yuidoc parses ALL directories during build:reference, polluting public/reference/data.json

[nbogie]

Most appropriate sections of the p5.js website?

Other (specify if possible)

What is your operating system?

Mac OS

Web browser and version

n/a

Actual Behavior

summary

During build:reference, the yuidoc stage for p5.sound incorrectly parses ALL p5.sound directories rather than src/, polluting public/reference/data.json (and src/content/reference/en/p5./) with junk entries.

A symptom:

npm run build:reference outputs errors:

Error saving MDX: Error: ENOENT: no such file or directory, open 'src/content/reference/en/p5/{import("@playwright/test").LaunchOptions} launchOptions.mdx'

(Further, if you were to then look at the generated public/reference/data.json and src/content/reference/en/p5./ you'd see other weird unintentional content from p5.sound tests (at least) in there).

Cause:

yuidoc for p5.sound is (and has been) processing more content than it should from p5.sound, including (but not limited to) its new examples/ and test/ folders which are not specifed in its config yuidoc.json.

Cause in depth:

In p5.js-website's src/scripts/parsers/reference.ts, parseLibraryReference calls saveYuidocOutput and by default that uses . as an input path for the yuidoc executable. Specifying an input path of . seems to override the intended paths: ["src"] specified in p5.sound's ./yuidoc.json config file so the yuidoc executable parses ALL directories except for those explicitly mentioned in its exclude list (currently: dist,out,node_modules) in that same config file.

While one could argue we should just exclude all unwanted directories in that config, this requires more frequent maintenance and actually requires seeing into the future, particularly as PR #1223 will now allow building the reference from local p5.sound dirs where the user might have any number of other unanticipated directories in their local p5.sound (e.g. .git or .vscode/ or .worktrees/ or .codex/ or .claude/)

suggested solution

Pass an input path of src to the invocation, overriding the default .. The saveYuidocOutput function already allows for this so it'd be something like:

saveYuidocOutput('p5.sound.js', 'data-sound', { inputPath: "src" });

Alternatively, it is likely possible to pass NO input path to yuidoc on its cmd-line invocation and instead have it rely purely on its config file to set up its paths. (I haven't confirmed this)

Expected Behavior

npm run build:reference should not generate unexpected unwanted content into src/content/reference or public/reference/data.json

Steps to reproduce

1. run npm run build:reference

2. observe error(s) including

Error saving MDX: Error: ENOENT: no such file or directory, open 'src/content/reference/en/p5/{import("@playwright/test").LaunchOptions} launchOptions.mdx'

3. look in the generated public/reference/data.json
   e.g.

grep "tests/integration" public/reference/data.json

or more generally

grep '"file": "' public/reference/data.json | grep -v '"file": "src'

...to see all entries in the reference data.json that don't start with a path of "src"

4. look in the generated src/content/reference/en/p5./
   e.g.

find src/content/reference/en/p5./

Would you like to work on the issue?

yes

[ksen0]

Thanks @nbogie assigned!

[nbogie]

Hi @kunstewi, this might be of interest - I know you had to fix p5.sound yuidoc.json recently.

In short, p5.js-website was invoking yuidoc . for p5.sound so . was being used as an input path, even though the config file explicitly states only "src" and it was parsing everything.

[kunstewi]

Sure @nbogie I'd take a look on this, once i get it done with the p5.sound local build PR.