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
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
