Reference Pages

[ogbabydiesal]

Just added a reference page for the Oscillator class to test compatibility with this library and the new p5 site.

this project does not use grunt currently but if it must let's chat about adding that to the build process!

therefore

$ npm run grunt yui:dev

did not work so I used the standard install command from the YUIDoc homepage as follows...

npm -g install yuidocjs

I then created a reference for the Oscillator class in src/Oscillator.js and built the reference page using

yuidoc .

Output was built to the 'out' folder...

I confirmed the reference was built and looks good by

cd out 
python3 -m http.server

Question: anything to consider or add so that the reference pages and source code/this library is compatible with the p5 website?

@Qianqianye @raclim can you make it so that I can tag Ken in this discussion?

[limzykenneth]

For the reference, specifically the descriptions, you will need to follow the format here: https://github.com/processing/p5.js/blob/main/contributor_docs/contributing_to_the_p5.js_reference.md as in just go straight into the description text (with first line as the brief description) instead of adding a title. ie.

/**
 *  <a href="/reference/#/Oscillator">Oscillator</a> 
 *  <p>Creates an oscillator.</p>
 *  @class Oscillator
 *  @constructor
 *  @param {Number} [freq] frequency defaults to 440Hz
 *  @param {String} [type] type of oscillator. Options:
 *                         'sine' (default), 'triangle',
 *                         'sawtooth', 'square'

The first line where it is a link to the Ocsillator is not needed and the second line don't need the <p> tags. You can checkout the inline reference of p5.js source code for more.

You also don't need to check the generated HTML from YUIDoc as we don't use them (we use the generated data.json file). As long as the command build and does not error it should be fine.

[ogbabydiesal]

ok excellent - just updated the oscillator + SinOsc, SawOsc, SqrOsc, TriOsc reference pages.

[Qianqianye]

Thanks @tmartinez88.
Ken, please feel free to review the updated reference page, and leave comments here, thanks! @limzykenneth

[ogbabydiesal]

hi @limzykenneth is there a way we can test the output data.json from yuidoc with the library and view the hosted examples to test?

i've been adding examples and reference docs and wanted to be able to check to make sure docs are looking ok

i see this documented here in the docs but it refers more to the core library and its build process: https://github.com/processing/p5.js/blob/main/contributor_docs/contributing_to_the_p5.js_reference.md#generating-and-previewing-the-reference

[limzykenneth]

@tmartinez88 For that it is more complicated but I'll try to break it down into steps

1. Build the full p5.sound.js library with the inline reference comments
2. Copy the library file into a local copy of the p5.js library repo, in the lib/addons/ folder (replacing the existing ones)
3. Run npm run docs on the p5.js library repo
4. Copy both data.json and data.min.json from the p5.js library repo's docs/reference folder into the p5.js-website-legacy repo's src/templates/pages/reference folder.
5. Run npm run watch in the p5.js-website-legacy repo to preview the build site with the reference.

It is quite convoluted and for the most part I can help take care of making sure the reference is in the right format and can work with the rest of the site, so you don't have to go through all these steps above. As long as the contents needed are there, I should be able to finese them even if the format are not fully there yet.

[ogbabydiesal]

got it! if i'm feeling brave closer to the end I will try this out :) thx @limzykenneth