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.

break recap, and what’s next

  • added some inline documentation for the p5.serial library, so it’ll hopefully be able to join the other libraries on the p5 reference page. working on that was a way for me to dip my toes into git, contribute to an awesome open source community, and spend time reading serial functions line by line. i never fully wrapped my head around serial communication during the semester, and i found writing documentation to be helpful for that.
  • read ursula k leguin’s the dispossessed. into it. i agree with marc below and also with myself below:

Screen Shot 2016-01-26 at 11.24.03 PM

  • said i was going to summarize a bunch of articles and books about BIG DATA MASS SURVEILLANCE APOCALYPSE, but only summarized one article fully. added many things to my “to read” folder. continued and continue to think everything is related to work foucault and harcourt have already done.
  • spent precious invaluable 1:1 time with a git-obsessed friend who helped me understand a few basic git commands and gh-pages. he also helped me clean up my idf meme generator because he’s a css wizard. still lots to do on that project, but i just can’t overstate the importance of those uninterrupted, 3-hour chunks of working through stuff together.
  • submitted a proposal to the beyond the bars conference at columbia with a thinker/organizer/mom who i respect and admire a ton.

in store for this semester is a magical whirlwind of thinking/making candy to stretch and titillate every corner of my brain and maybe make me very tired, but whatever:

  • social hacking with lauren mccarthy and kyle mcdonald
  • radio gaga with surya mattu
  • personal narratives with anna deveare-smith. because nothing cures social anxiety like a theater class!
  • performance of politics with tavia nyong’o (tisch performance studies) and eric lott (CUNY grad center)
  • software engineering pilot internship. i’ll be a t.a. in a coding class in a brooklyn high school.
  • presenting a workshop about 596 acres at bronx tech month

“watch this space,” as they say.*


*who says that?