p5 documentation with yuidoc and gh-pages

i mentioned in the last post that i was adding inline documentation for the p5.serialport. this afternoon, jason sigal walked me through formatting the documentation. the p5 website uses yuidoc to automatically generate a formatted reference page based on tags in the raw code. we installed yuidoc but had to try a few different file structures before it would generate the one p5.serialport.js file we wanted, without generating pages for all the other p5 documentation that was also in the folder.

we created a lib folder where we put the p5.serialport.js file. then, the index.html files of all the examples that linked to the p5.serialport.js file had to be relinked and directed through this new lib folder.

Screen Shot 2016-01-29 at 3.26.37 PM

then, we created a yuidoc.json file in the folder that told yuidoc to generate documentation only for the files in the lib folder.

Screen Shot 2016-01-29 at 3.26.31 PM

the outdir folder was the output of this process, and it holds all the files for the new documentation webpage. the page looks like this:

Screen Shot 2016-01-29 at 4.54.23 PM

there’s still a lot to do:

  • you can tell that the example functions aren’t correctly spaced.
  • this reference could use a better description at the top of the page
  • we need to figure out how to link to tom igoe’s examples, and add more serial examples in general
  • we’d also like to figure out how to generate this page to look like the rest of the p5 libraries, which requires working with the custom p5 yuidoc template.

as i continue to work on this, i’ll make changes locally, review, and ultimately push the changes back up to shawn’s gh-page for this documentation.

when i think about everything ahead of me, it’s helpful to take a breath and remember that i hadn’t even heard of sublime text when i started this project. i still feel like i’m fumbling around most of the time, but progress is happening. this has been a great way to learn about version control with github and be in touch with lots of awesome folks: shawn who wrote the serial library, lauren who originally created p5, and jason who wrote the sound library.

Leave a Reply