Skip to content

scripts.md

Latest commit

 

History

History
81 lines (49 loc) · 4.29 KB

scripts.md

File metadata and controls

81 lines (49 loc) · 4.29 KB

Content Scripts

This repo includes a few scripts to pull content from external sources, primarily the p5.js repo.

They are all runnable via npm scripts.

Testing the docs of your fork

p5.js

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 #:

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.

Actually, it's also possible to test against a branch from your local repo. This means you can test without first pushing to github (but you will still need your changes checked into a branch, locally).

To do this, just supply the file-path to the local repo, instead of the url to the repo.

npm run custom:dev path-to-local-repo#yourBranch

For example, if you have a local p5.js clone repo called p5.js as a sibling directory to the website, you could run the following:

npm run custom:dev ../p5.js#yourBranch

p5.sound.js

If you want to preview changes to the p5.sound.js documentation from your local machine, you can use the LOCAL_P5_SOUND_PATH environment variable. This will copy your local p5.sound repository directly instead of cloning it from GitHub, which is useful when testing your own unpushed changes or custom branches.

Provide the file-path to your local p5.sound repository when running the reference build script. For example, if you have a local clone called p5.sound as a sibling directory to the website, you could run:

LOCAL_P5_SOUND_PATH=../p5.sound npm run build:reference

otherwise if you have added the file-path to the p5.sound.js build in your .env file using the LOCAL_P5_SOUND_PATH environment variable, you could simply run:

npm run build:reference

This will copy your local files over (ignoring node_modules and .git folders to speed up the process) and build the reference documentation using those files.

Resetting your changes

When you're done, you can run this command to reset your changes:

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.

Contributor Docs Build Script

npm run build:contributor-docs copies the contributor docs from the p5.js repo and places them into the contributor docs content collection.

Reference Build Script

npm run build:reference parses the inline documentation in the p5.js source code (the JSDoc comments) and generates the pages in the reference collection. Because the directly inline documentation for p5.js is only in English, this script will only update the English translation of the reference.

Contributors List Build Script

npm run build:contributors parses the list of contributors from the all contributors config file in the p5.js repo and adds entries in the people collection for anyone who is missing. These are used to render the list of contributors on the People page. This script will not remove or update existing entries, that must be done manually.

Update p5 version Build Script

npm run build:p5-version reads the latest version of the p5.js library (for example, "2.19.3") and updates the website config to use that version of the library for embeds and download links across the site.

Search Indices Build Script

npm run build:search generates metadata about the content of the website so the search functionality can show relevant results. This script should usually be run after any of the above scripts are run.