Add document about the v2 reference-generation process by nbogie · Pull Request #8509 · processing/p5.js

nbogie · 2026-02-08T19:34:44Z

Changes:

Adds two new documents, makes no other changes.

Add contributor_docs/reference_generation_process.md

section on main reference generation process
- flow diagram
- description of process steps and important files
minimal section on search index generation (diagram only). I don't want to tackle this topic further in this PR - happy to delete, if that's better.

I've tried to add a little colour to the flow diagram to help distinguish between actions which run in p5.js repo versus p5.js-website repo. However, we're at the mercy of the css that just inverts the mermaid diagram colours to get dark mode. Happy to resort to no extra colour if preferred.

Add contributor_docs/type_generation_process.md
- sparse description (lists main flow and processes, input and output files)
- flow diagram
- description of the patch process and example of patch syntax to use

nbogie · 2026-04-27T17:31:15Z

If necessary/useful, I can raise a separate PR for the documentation of the type-generation process. (Until today i was writing them up in the same document.)

p5-bot · 2026-04-29T23:02:04Z

Continuous Release

CDN link

https://raw.esm.sh/pr/p5@bf8a215/lib/p5.min.js

Published Packages

https://pkg.pr.new/p5@bf8a215

Commit hash: 3347de6

Previous deployments

`075971c`

`2a4a117`

This is an automated message.

ksen0

Nice, thank you! cc @perminder-17 @davepagurek @doradocodes

ksen0 · 2026-04-29T23:02:34Z

+
+## Need to know?
+
+You don't need to know _any_ of this to successfully write and maintain the reference comments in the p5.js library!  If you've questions about that, see [Contributing to the p5.js reference](./contributing_to_the_p5js_reference.md).


Minor: I think this is a good first paragraph for the doc overall?

ksen0 · 2026-04-29T23:03:34Z

+
+You don't need to know _any_ of this to successfully write and maintain the reference comments in the p5.js library!  If you've questions about that, see [Contributing to the p5.js reference](./contributing_to_the_p5js_reference.md).
+
+Warning: This describes how things work in April 2026 and is quite likely out of date!


Maybe state that this works as of april 2026, but link to the scripts being described. I know they're linked below but just for clarity of, "if this is out of date, please consult source of truth here"

ksen0 · 2026-04-29T23:04:47Z

+
+You can run it locally and observe the outputs.
+
+It is currently run by [a release process workflow](../.github/workflows/release-workflow-v2.yml) on Github Actions CI.


Absolute link probably needed because these docs will end up on the website where relative link will feel broken

davepagurek · 2026-05-03T18:00:02Z

+
+\* The convert script has _also_ generated `/docs/parameterData.json` which is used by the friendly error system (FES) at runtime to validate function parameters.  We won't discuss that further here.
+
+#### Excerpt of /docs/reference.data.json


Small typo I think:

Suggested change

#### Excerpt of /docs/reference.data.json

#### Excerpt of /docs/reference/data.json

davepagurek

This looks great @nbogie!

perminder-17

Looks good to me @nbogie

* list key scripts up front * bring "do you need to know this?" earlier * absolute links to relevant source docs throughout add end section on contributing to this document

nbogie · 2026-05-04T15:07:41Z

Thanks all!

Incorporated all those corrections/suggestions,
added an end section "contributing to this document", and
made a couple of minor readability tweaks

ksen0

Hi @nbogie ! I just spotted a couple of super minor things. I'll be making the RC in a couple of days and I'll merge this into that. I can apply the one type fix needed if you don't have time to touch it before then. Thanks again for all your work on fleshing out these docs!

ksen0 · 2026-05-05T07:45:59Z

+The process described in this document does not apply to the types for the p5 v1 library.  There are (often out-of-date) types at [definitely-typed](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/p5), packaged to npm as @types/p5. This document only discusses the types for p5 v2.
+
+
+## Aside: "Why not just do X...


Minor: missing closing "

ksen0 · 2026-05-05T07:47:34Z

+
+#### Summary: 
+
+Loads the generated `./docs/reference/data.json`


I didn't run this locally but I'd imagine this should be a list but wouldn't show up as one? Feel free to ignore if I'm wrong

Good spot, either I meant that or certainly it reads better as a list. I added a little to emphasise that this was the end of the focused flow, and to list briefly what will consume the MDX files downstream.

ksen0 · 2026-05-05T07:48:10Z

+
+## Need to know?
+
+You don't need to know _any_ of this to successfully write and maintain the reference comments in the p5.js library!  If you've questions about that, see [Contributing to the p5.js reference](./contributing_to_the_p5js_reference.md).


nbogie · 2026-05-05T11:54:51Z

Incorporated typo + formatting corrections, thanks Kit!

nbogie added a commit to nbogie/p5.js that referenced this pull request Feb 8, 2026

moving reference_generation_process.md to separate PR processing#8509

57f4915

nbogie mentioned this pull request Feb 8, 2026

[p5.js 2.0 Bug Report]: guide "contributing to the p5js reference" is out of date for v2.x #8454

Closed

17 tasks

nbogie added a commit to nbogie/p5.js that referenced this pull request Feb 12, 2026

moving reference_generation_process.md to separate PR processing#8509

690ab50

nbogie marked this pull request as ready for review April 27, 2026 17:30

add docs for reference-generation and type-generation processes

13d5fa9

nbogie force-pushed the nb-add-ref-gen-process-doc branch from 016ccef to 13d5fa9 Compare April 27, 2026 23:02

Merge branch 'dev-2.0' into nb-add-ref-gen-process-doc

2a4a117

ksen0 approved these changes Apr 29, 2026

View reviewed changes

davepagurek reviewed May 3, 2026

View reviewed changes

davepagurek approved these changes May 3, 2026

View reviewed changes

davepagurek mentioned this pull request May 3, 2026

[p5.js 2.0 Bug Report]: p5.Graphics.model() is not a function when used on secondary WEBGL p5.Graphics canvas #8671

Open

17 tasks

perminder-17 approved these changes May 3, 2026

View reviewed changes

ref-gen process doc: incorp feedback from kit+dave's review +

22679a8

* list key scripts up front * bring "do you need to know this?" earlier * absolute links to relevant source docs throughout add end section on contributing to this document

nbogie force-pushed the nb-add-ref-gen-process-doc branch from 1061b8e to 22679a8 Compare May 4, 2026 14:44

nbogie added 2 commits May 4, 2026 15:46

Merge branch 'dev-2.0' into nb-add-ref-gen-process-doc

c9b2659

minor readability tweaks to ref-gen process doc

075971c

ksen0 approved these changes May 5, 2026

View reviewed changes

nbogie added 2 commits May 5, 2026 12:30

fix typo

9cc8e98

improve summary of mdx generation step

3347de6


		## Need to know?

		You don't need to know _any_ of this to successfully write and maintain the reference comments in the p5.js library! If you've questions about that, see [Contributing to the p5.js reference](./contributing_to_the_p5js_reference.md).


		You don't need to know _any_ of this to successfully write and maintain the reference comments in the p5.js library! If you've questions about that, see [Contributing to the p5.js reference](./contributing_to_the_p5js_reference.md).

		Warning: This describes how things work in April 2026 and is quite likely out of date!


		You can run it locally and observe the outputs.

		It is currently run by [a release process workflow](../.github/workflows/release-workflow-v2.yml) on Github Actions CI.


		\* The convert script has _also_ generated `/docs/parameterData.json` which is used by the friendly error system (FES) at runtime to validate function parameters. We won't discuss that further here.

		#### Excerpt of /docs/reference.data.json

	#### Excerpt of /docs/reference.data.json
	#### Excerpt of /docs/reference/data.json

		The process described in this document does not apply to the types for the p5 v1 library. There are (often out-of-date) types at [definitely-typed](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/p5), packaged to npm as @types/p5. This document only discusses the types for p5 v2.


		## Aside: "Why not just do X...


		#### Summary:

		Loads the generated `./docs/reference/data.json`

Uh oh!

Conversation

nbogie commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes:

Uh oh!

nbogie commented Apr 27, 2026

Uh oh!

p5-bot Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Continuous Release

CDN link

Published Packages

Uh oh!

ksen0 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davepagurek left a comment

Choose a reason for hiding this comment

Uh oh!

perminder-17 left a comment

Choose a reason for hiding this comment

Uh oh!

nbogie commented May 4, 2026

Uh oh!

ksen0 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nbogie commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nbogie commented Feb 8, 2026 •

edited

Loading

p5-bot Bot commented Apr 29, 2026 •

edited

Loading

ksen0 left a comment •

edited

Loading