GSOC Idea: Interactive documentation with autodoc

[Zack Maril]

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 

[David Nolen]

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

[Colin Jones]

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

[Zack Maril]

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

[Daniel Solano Gomez]

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

[Andy Fingerhut]

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