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 Mon, Mar 26, 2012 at 12:40 PM, Colin Jones <trptco...@gmail.com> 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.li...@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 > > > > On Sat, Mar 24, 2012 at 11:10 AM, Zack Maril <thewitzb...@gmail.com> > wrote: > >> > >> 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 clojure@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+unsubscr...@googlegroups.com > >> For more options, visit this group at > >> http://groups.google.com/group/clojure?hl=en > > > > > > -- > > You received this message because you are subscribed to the Google Groups > > "Clojure Dev" group. > > To post to this group, send email to clojure-...@googlegroups.com. > > To unsubscribe from this group, send email to > > clojure-dev+unsubscr...@googlegroups.com. > > For more options, visit this group at > > http://groups.google.com/group/clojure-dev?hl=en. > > > > -- > Colin Jones > @trptcolin > > -- > You received this message because you are subscribed to the Google > Groups "Clojure" group. > To post to this group, send email to clojure@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+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en > -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@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+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
