|GSOC Idea: Interactive documentation with autodoc||Zack Maril||3/24/12 8:10 AM|
Goal of project: Extend (or fork) autodoc such that it can create and run interactive documentation for any project.
Example for the take function:
Usage: (take n coll)
Returns a lazy sequence of the first n items in coll, or all items if there are fewer than n.
<textarea> (take 10 (range 20))</textarea> <button> Eval!</button>
[0 1 2 3 4 5 6 7 8 9]Added in Clojure version 1.0
And then the user could change the code in the browser, it would be sent off to the server, and the new user would get the answer back:
Example: <textarea> (take 5 (range 20))</textarea> <button> Eval!</button>
Output: [0 1 2 3 4]
To make this work, autodoc would need to be extended in two major ways:
1. When generating the html, autodoc would look for metadata within each definition. If it found :examples within the data, then it would add in a number of <textarea> elements and eval buttons prefilled with the given examples.
2. Have it ship with a webserver that runs something similar to tryclojure and has all of the routes set up for the documentation to work automagically. A very basic use of clojail. An interesting challenge would be finding a way to get outputs besides text to work (things like charts for incanter).
Conceptually, this isn't too hard to imagine as a project. The main brunt of the work would be writing all of the examples for each project. Even then, there are a ton of examples on clojuredocs.org that are under the EPL license. Having interactive documentation would be pretty cool though. The only place I have seen it so far has been in Mathematica, and that was only after you bought the program. If people are interested in this being made, I'll be the first to volunteer as a student.
Would people be interested in this as a project for GSOC?
|Re: GSOC Idea: Interactive documentation with autodoc||David Nolen||3/26/12 7:09 AM|
Having examples in the Clojure source has come up before and it's probably not going to happen. Also the repl-y project that is now integrated into lein 2 has this functionality. However I think you're on an interesting track as far as how Mathematica works. I don't think anyone has tackled a rich interactive REPL with good integrated graphics support (that is also interactive). I recall that Chas Emerick and others were interested in this.
|Re: GSOC Idea: Interactive documentation with autodoc||Colin Jones||3/26/12 7:40 AM|
One thing missing from reply's clojuredocs integration is the ability
to have a local cache of the examples. Currently, we're just making an
API call every time (using the clojuredocs-client library), which is
great for getting off the ground and for having the latest examples,
but not so great for offline work and speed.
I talked very briefly about this at Clojure/West with Lee Hinman
> "Clojure Dev" group.
|Re: GSOC Idea: Interactive documentation with autodoc||Zack Maril||3/26/12 11:11 AM|
Here's one way of going about getting the bare bones for examples:
Simple examples with autodoc:
The changes to autodoc required to make this happen:
Adding in metadata to the + function:
It sounds like the community has rejected the inclusion of examples in the past. But, for reference, it's really easy to include examples and make them work out of the box. You can just include whatever code you want and eval it (no security/speed worries since it is static html you yourself are compiling).
|Re: GSOC Idea: Interactive documentation with autodoc||Daniel Solano Gómez||3/26/12 11:24 AM|
On Mon Mar 26 16:11 2012, Zack Maril wrote:> past. But, for reference, it's *really* easy to include examples and make
On a related not, just because examples won't be added to the core, that
(alter-meta! #'clojure.core/+ assoc :examples […])
This way all of the example code could be kept outside of the core but
|Re: GSOC Idea: Interactive documentation with autodoc||Andy Fingerhut||3/28/12 4:08 PM|
My fork of cd-client has code to create a local snapshot of all examples, see-alsos, and comments in clojuredocs.org, save it to a file, and switch to "local mode", which pulls all results from the snapshot file instead of clojuredocs.org.