GSOC Idea: Interactive documentation with autodoc

Showing 1-6 of 6 messages
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:
 

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.
Example: 
<textarea> (take 10 (range 20))</textarea> <button> Eval!</button>
Output: 
[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.   
Example definition:
(defn take
  "Returns a lazy sequence of the first n items in coll, or all items if
there are fewer than n."
  {:added "1.0"
   :static true
:examples ['(take 5 (range 10)),'(take 3 (drop 5 (range 1 11)))]}
  [n coll]
  (lazy-seq
   (when (pos? n)
     (when-let [s (seq coll)]
      (cons (first s) (take (dec n) (rest s)))))))
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?
-Zack 

Re: GSOC Idea: Interactive documentation with autodoc David Nolen 3/26/12 7:09 AM
Zack,

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.

David

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en

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
(author of clojuredocs-client) and Zack Kim (of clojuredocs fame), and
it sounded like they're open to this idea and even have ideas about
how it might work. I'm not sure whether it's big or interesting enough
for a GSOC project, or even which projects would be involved, but it's
certainly something I'd like to have.

> "Clojure Dev" group.
> To post to this group, send email to cloju...@googlegroups.com.


> To unsubscribe from this group, send email to
> clojure-dev...@googlegroups.com.

> For more options, visit this group at
> http://groups.google.com/group/clojure-dev?hl=en.

--
Colin Jones
@trptcolin

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). 
-Zack
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:
> Here's one way of going about getting the bare bones for examples:
>
> Simple examples with autodoc:
> http://clojure-examples.herokuapp.com/clojure.core-api.html#clojure.core/+
>
> The changes to autodoc required to make this happen:
> https://github.com/zmaril/autodoc/commit/4cb3d7aa1079f0859b129469ea1163e306a1f5ef
>
> Adding in metadata to the + function:
> https://github.com/zmaril/clojure/commit/2d4902239d8595af74cf17264414a51128de639a
>
> 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).
> -Zack

On a related not, just because examples won't be added to the core, that
doesn't mean it can't be added externally.  You can always do something
like:

(alter-meta! #'clojure.core/+ assoc :examples […])

This way all of the example code could be kept outside of the core but
still associated with the core functions.

Sincerely,

Daniel

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.

https://github.com/jafingerhut/cd-client

Andy

On Mar 26, 2012, at 7:40 AM, Colin Jones wrote:

> 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
> (author of clojuredocs-client) and Zack Kim (of clojuredocs fame), and
> it sounded like they're open to this idea and even have ideas about
> how it might work. I'm not sure whether it's big or interesting enough
> for a GSOC project, or even which projects would be involved, but it's
> certainly something I'd like to have.
>
>
>
>
> On Mon, Mar 26, 2012 at 9:09 AM, David Nolen <dnolen...@gmail.com> wrote:
>> Zack,
>>
>> 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.
>>
>> David