Documentation for RDF.rb in iRuby notebooks?

[tombaker]

I wanted to suggest that documentation for RDF.rb be moved into iRuby notebooks -- i.e., Jupyter notebooks running the Ruby kernel.

Github now supports the rendering of Jupyter notebooks in the browser (see my gist of some notes about Ruby). Some advantages of putting documentation into Jupyter:

• broken code examples could be detected simply by running a notebook from the top.
• users could run jupyter nbconvert to convert the documentation into HTML, PDF, or one-cell-at-a-time Powerpoint-like presentations.

[gkellogg]

Seems like an interesting idea. Right now, documentation references rubydoc.info, which is updated periodically from built-in yardoc tags, and having the documentation be derived from embedded yardoc is a big plus. I don't know how Jupyter works, but I'd be dis-inclined to maintain separate source for this that was divorced from the actual Ruby source, but the prospect of working examples in the documentation is intriguing.

Note that most examples have duplicates in the specs, so there shouldn't be too many examples that fail. If so, that's obviously a bug which should be addressed.

I certainly am open to considering this, though, and we should continue the conversation.