self discovering, self documenting ofxAddons

this summer Kyle mentioned the idea of having github scripts to discover and document addons. during Art&&Code I brought this up to Greg Borenstein and he went ninja on a Rails app to do just that. It looks at github for repos with ofx in them and then creates admin tools for publishing them.

for the time being the prototype lives here:

The moderation system allows being able to delete addons that aren’t openframeworks related from the list, adding categories, and parsing README’s to look for things like screenshots and dependencies, original author.

It will also have some logic to prioritize the “right” fork of the repo if it finds multiple ones.

This will also enforce using the convention described here:

we’d love input on this!

What are the categories? Who should categorize them? Should we depend on the addon authors to write the descriptions? can we user-submit descriptions? where should this live? could it be integrated into the main of site? should it be considered separate like

how can this integrate with ofReference thing that is going to happen next week?

any thoughts so welcome!

how can this integrate with ofReference thing that is going to happen next week?

Spitting out markup is easy-peasy, part of why I decided that the best way to keep an up-to-date-ish reference was markdown+github. Ruby does markup with kramdown and the parsing rules for github flavored markdown (which I think I’ll be using for the docs) live on the github site, so adding them in is easy. I say: find something, spit out markdown for it, flesh it out by hand.

Hey Josh,

just so i understand you’re talking about generating documentation for addons we discover? or if you aren’t talking about that maybe I should have stated my question in that direction.

Ideally we’d be able to create mark up for the addons that are discovered, and potentially even without the author having to do it themselves, but could be a user contributed thing.

Am I off base here?

As a starting point here were the categories that James and I came up with on looking at the existing list of addons:

* iOS
* Physics
* Hardware Interface
* Sound
* Web/Networking
* Animation
* Graphics
* Utilities
* Computer Vision

We tried to base them around what you’re trying to do with your code since that’s usually where you start when you’re looking for an addon. Additions/suggestions welcome!


Exactly, so you could come across ofxJosh and maybe just spit out:

Created {date} by {dev} lives at {repo}  
###void talk()###  
###void shutup()###  

Totally hypothetical, but seems do-able, no? Of course someone would have to go in by hand and write out what talk and shutup do, because no parser is going to figure out anything meaningful about it, but at least you have a start.

@Josh yeah i think hypothetically this is great. enough questions come to mind immediately to make me feel like maybe this part is getting ahead of ourselves.

who is that someone that writes the markdwn? who has access to the addon markdown repo? what happens when addons change?

I think if we discover a lot of the successes and failures of this approach with the ofReference push then we can think of how to take the next step for addons. but for now just having a list of categorized addons is a big win and tough enough =)

Yeah, no big hurry with it. I just thought it might be useful to spit out some v. basic documentation for an addon. In theory you could automate that commit/push to a fork of ofReference that I’d then just merge in and flesh it out myself since for some masochistic reason I like writing tech documentation.

I’m going to mind the ofReference, hopefully I can get enough people forking and submitting pull reqs that it’s useful. Either that or I’ll just write it all myself w/Roxlu doing a whole bunch of tiny codesnippets; either way is fine with me :slight_smile:

Updated list of categories. Revised after we went through and assigned all the addons to a category:

* Animation
* Bridges
* Computer Vision
* Graphics
* Hardware Interface
* iOS
* Physics
* Sound
* Typography
* Utilities
* Video/Camera
* Web/Networking

Site’s looking pretty good now. Just pushed it live (if that doesn’t show up for you because the DNS is still propagating, try:

this is awesome

Really nice work. Eventually we should really try to get this as part of the openFrameworks website though. I think it’ll be better if it’s an official website and directly linked to OF.

@seth I totally agree, but for the same reason that we need a self-discovering addon thing, we also need something that can live outside of the of site administration so that it can have a life of it’s own without needing to require permission from people to function.

if we served this page on the addons section that would be amazing though! We hope that it can find some sort of official home inside of

Right, I don’t want to hijack this thread. We talked about addons as part of the website in the other thread to some length. My suggestion was allowing owners to add/edit their own addons (which eliminates the need for administration to a large degree). But of course, we can’t do anything on without approval and the core devs seem busy. So this is the next best option; keep it up!

Would be nice for to maybe redirect to this site maybe because a lot of the links are broken.

One possible middle-ground solution that might be nice would be to have point to this site. That’s something that whoever’s in charge of the website could do just by setting an A-name of C-name record in their DNS. That would let it be integrated into the website while still allowing others outside to do all of the maintenance.

By the way, the source for the site is here: So if we vanish off a cliff someone else could also just pick it up and maintain it.

I’ll also set up the site to do regular db dumps and check them into that repo as well so that the data can’t be lost either.

Great work so far!
Two things I noticed: ofxFenster is in there twice (du to manual code-copying), and memo’s MSALibs is missing because it doesn’t have an ofx prefix (at least not in the repo name). Just wanted to point them out, I’m not sure we can do anything about that.

[quote=“joshuajnoble, post:7, topic:7909”]
I’m going to mind the ofReference, hopefully I can get enough people forking and submitting pull reqs that it’s useful. Either that or I’ll just write it all myself w/Roxlu doing a whole bunch of tiny codesnippets; either way is fine with me :)[/quote]
Did that thread about ofReference vanish? I can’t find it. Or am I confused, and there was never a thread? What I wanted to ask is: What kind of info do you want to see in ofReference? Cause what I see now looks similar to what would be generated by e.g. doxygen, so wouldn’t it be best to take/flesh out the doxygen work on

Hey this looks great.

I’d really like to see this as part of the official oF site which is in dire need of a strip down / refocus in lots of areas (documentation / gallery / community)

Really great work!

ofxFenster is in there twice

Yes. But that kind of makes sense. But it’s just not really transparent why. The one by me, is the rewrite of ofxFenster based on ghost and the other one is the original version based on glut. Fishkingsin uploaded the download from the forums to github.

i’ve been out of the loop for the last couple days, but just wanted to say:

  • is awesome. this is exactly the kind of thing i was hoping for :slight_smile:

  • i totally support ofReference, but don’t forget about all the hard work that’ gone into the current documentation. e.g. if there’s any way to scrape that info and bring it into the git repo, i think you’re off to a great start. which brings me to my main point…

  • “normal” documentation happens inline with something like doxygen. inline documentation is great if it’s already there, but i think for something like OF it can be hard to add it after the fact. i doubt zach, theo or arturo want to read through hundreds of lines of comments describing how things work before they decide to merge documentation-only changes. so the ofReference idea is very strong, because it decouples documentation from the source code, and puts maintenance of documentation into the hands of more people. here’s a vision for where ofReference might be headed:

1 josh adds elliot, james, greg, and whoever else is super interested to the ofReference repository as admins
2 greg or chris figure out how to populate ofReference with the already existing OF documentation
3 everyone hacks like crazy and adds documentation. the people hacking hardest are the admins/are made admins.
4 there is a parallel effort to generate the documentation HTML for from the github repo

if i remember correctly, the current documentation has a wordpress backend, which is a noble idea but i think ultimately isn’t accessible or transparent enough.

@bilderbuchi doxygen only works if there’s doxy comments in the code, which isn’t going to happen. I think we need something simple, system agnostic, github friendly and that doesn’t interfere with the source code as is. I’ll make a thread for this where we can discuss further: