Re: ClojureDocs.org week 1
What I've noticed is that conventions on doc string indentation is all over the place. Combine that with the fact that folks build tables and columns by hand, and a really simplistic rule doesn't work so much. I recommend you just grab the remove-leading-whitespace function from the autodoc program and use it. It's here: http://github.com/tomfaulhaber/autodoc/blob/master/src/autodoc/collect_info.clj#L13 That seems to make all the doc strings I've encountered in the wild format up pretty well. HTH, Tom On Jul 17, 2:52 am, Tassilo Horn tass...@member.fsf.org wrote: Hi Zack, I just had a look at ClojureDocs.org and it's really neat! Some observations I made: - When I view the docs of let's say clojure.set/rename, the clojure.set part is a link. But instead of pointing to to clojure.set summary page, it is only http:. - In the source section, not all referenced vars (called functions) are linked. - All lines of multi-line docstrings are except the first are indented which looks quite ugly. Well, that's not ClojureDoc.org's fault. It seems that it's a clojure convention to write docstrings like: --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- instead of like --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- which is the convention in any other lisp I know. Has this convention a reason, or is this only Rich's personal preference others simply adapted? Anyway, really neat! :-) Bye, Tassilo -- 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
Re: ClojureDocs.org week 1
Tom- Definitely helps, I'll add this on the next var update cycle. Thanks, Zack. On Jul 18, 12:17 pm, Tom Faulhaber tomfaulha...@gmail.com wrote: What I've noticed is that conventions on doc string indentation is all over the place. Combine that with the fact that folks build tables and columns by hand, and a really simplistic rule doesn't work so much. I recommend you just grab the remove-leading-whitespace function from the autodoc program and use it. It's here: http://github.com/tomfaulhaber/autodoc/blob/master/src/autodoc/collec... That seems to make all the doc strings I've encountered in the wild format up pretty well. HTH, Tom On Jul 17, 2:52 am, Tassilo Horn tass...@member.fsf.org wrote: Hi Zack, I just had a look at ClojureDocs.org and it's really neat! Some observations I made: - When I view the docs of let's say clojure.set/rename, the clojure.set part is a link. But instead of pointing to to clojure.set summary page, it is only http:. - In the source section, not all referenced vars (called functions) are linked. - All lines of multi-line docstrings are except the first are indented which looks quite ugly. Well, that's not ClojureDoc.org's fault. It seems that it's a clojure convention to write docstrings like: --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- instead of like --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- which is the convention in any other lisp I know. Has this convention a reason, or is this only Rich's personal preference others simply adapted? Anyway, really neat! :-) Bye, Tassilo -- 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
Re: ClojureDocs.org
Islon- See the week 1 post on the CD.org group (http:// groups.google.com/group/clojuredocsorg/browse_thread/thread/ af7edbf85a6607c4) as to where this fits in on the timeline. Lee- Very cool, I've added it to the UserVoice page. Daniel- I agree, a great search experience is key for documentation sites, see the week 1 post for more info. Avram- I believe I missed addressing this in the week 1 post, thanks for the reminder. -Zack On Jul 16, 11:56 am, Avram aav...@me.com wrote: A few thoughts... It might be interesting to allow examples to be rated. Quality or usefulness of the provided example could then be inferred from the rating and highly rated examples could bubble to the top or have the associated rating prominently shown. ~A On Jul 16, 10:29 am, Lee Hinman matthew.hin...@gmail.com wrote: Had another suggestion, As an example contributor, It would be really nice to see a list of functions that have no examples yet at a glance, so if I wanted to work on adding examples I could go through a list and work on functions that have no examples. I believe the clojure-examples appspot wiki used to dim out functions that didn't have any examples (I don't think it does this any more), which was very helpful. If we did this, we could even have a percentage meter to work toward 100% API example coverage :) - Lee -- 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
Re: ClojureDocs.org week 1
Hi Zack, I just had a look at ClojureDocs.org and it's really neat! Some observations I made: - When I view the docs of let's say clojure.set/rename, the clojure.set part is a link. But instead of pointing to to clojure.set summary page, it is only http:. - In the source section, not all referenced vars (called functions) are linked. - All lines of multi-line docstrings are except the first are indented which looks quite ugly. Well, that's not ClojureDoc.org's fault. It seems that it's a clojure convention to write docstrings like: --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- instead of like --8---cut here---start-8--- (defn my-function Do magic and return a spell. More detailed docs... bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla [] (let [spell (do-magic)] (if (castable? spell) spell (alternative-spell sepll --8---cut here---end---8--- which is the convention in any other lisp I know. Has this convention a reason, or is this only Rich's personal preference others simply adapted? Anyway, really neat! :-) Bye, Tassilo -- 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
Re: ClojureDocs.org
Hi. Does clojuredocs expose any external API (json, xml... rest, webservices, etc) so I can access the docs from my code? Islon On Jul 13, 11:40 pm, j-g-faustus johannes.fries...@gmail.com wrote: On Jul 13, 8:37 pm, Paul Moore p.f.mo...@gmail.com wrote: Can I suggest omitting the Table of contents sidebar when printing? I've not tried printing the document to see how it looks, but removing the sidebar would be an essential starting point... Why would anyone want to print it? I occasionally print longer texts like specifications, but for reference material like Javadoc,ClojureDocs, the Ruby cheat sheet and this page, I think HTML is a far superior format due to links and browser search. And 40+ loose single sheets is a rather cumbersome package unless you have access to a book binder. But if at least two people feel that they would really like to print it out, I can skip the TOC on print. (Making it look _nice_ on paper is a whole different ballgame, then I'd have to look into pagination and page layouts, perhaps by converting to DocBook or LaTex. That's outside the scope of what I intended to do.) On Jul 13, 10:04 pm, Meikel Brandmeyer m...@kotka.de wrote: Some comments after quickly skimming through: ... PS: I'm apologise if some this seems to be nit-picking. Not at all, I'm still learning the language and happy to get the details clarified. The second form of condp and the #_ were omitted simply because I didn't know about them, thanks for the heads-up. For quoted lists, I take your point. For the sequence operations examples it was somewhat deliberate, in that a sequence is a very different datatype from a vector but pretty much the same as a list. I had a bug in some code that conj'ed elements onto a vector, but for some reason it would switch direction in the middle and start adding elements at the opposite end. It took me a while to figure out that it was because concat'ing two vectors doesn't return a vector. So I wanted to emphasize that using a sequence op on anything other than a list is also a conversion from one datatype to another. But I'll take another look, there may be better ways. Thanks for your comments, much appreciated. I'll include them with the next update. Sincerely, jf -- 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
Re: ClojureDocs.org
Had another suggestion, As an example contributor, It would be really nice to see a list of functions that have no examples yet at a glance, so if I wanted to work on adding examples I could go through a list and work on functions that have no examples. I believe the clojure-examples appspot wiki used to dim out functions that didn't have any examples (I don't think it does this any more), which was very helpful. If we did this, we could even have a percentage meter to work toward 100% API example coverage :) - Lee -- 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
Re: ClojureDocs.org
Hi Zack, I just take a quick look at your site and must say that I'm impressed. This is going to become one of the utilities I constantly keep open in the background while developing. Especially since features like the Var cross-referencing tend to make easier to get the big picture. One thing I immediately wanted to do is browse the Enlive docs to learn about the templating code, but couldn't simply search for Enlive -- I had to either click the (less-visible) All libraries link or search for a known Var like defsnippet. A project search feature, or a unified search that will search in Vars as well project names, would be really helpful. Thanks for investing your time into this site. May it prosper and attract many prospective new Clojure developers :-) -Daniel -- 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
Re: ClojureDocs.org
A few thoughts... It might be interesting to allow examples to be rated. Quality or usefulness of the provided example could then be inferred from the rating and highly rated examples could bubble to the top or have the associated rating prominently shown. ~A On Jul 16, 10:29 am, Lee Hinman matthew.hin...@gmail.com wrote: Had another suggestion, As an example contributor, It would be really nice to see a list of functions that have no examples yet at a glance, so if I wanted to work on adding examples I could go through a list and work on functions that have no examples. I believe the clojure-examples appspot wiki used to dim out functions that didn't have any examples (I don't think it does this any more), which was very helpful. If we did this, we could even have a percentage meter to work toward 100% API example coverage :) - Lee -- 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
Re: ClojureDocs.org
On 13 Jul, 01:28, j-g-faustus johannes.fries...@gmail.com wrote: On Jul 13, 12:25 am, j-g-faustus johannes.fries...@gmail.com wrote: I made my own cheat sheet for private use over the past month or so, core functions only. It's at the 80% stage, I don't expect it will ever be 100%, but I have found it useful: http://faustus.webatu.com/clj-quick-ref.html Looks like the hosting provider put my Clojure cheat sheet under review, I guess they found it suspicious... :) It seems to have passed approval, so it is available again. In the context of this thread, the cheat sheet is primarily an argument on how to best structure the information. Personally I like the compact format of having categories, names, description and examples all on the same page (to the extent that a 6k line page can be called 'compact'), perhaps combined with links to more extensive documentation. YMMV, and I'm not sure if the format can be made to scale to the scope and community nature of ClojureDocs. But some form of categorization would be nice. jf -- 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
Re: ClojureDocs.org
On 12 July 2010 23:25, j-g-faustus johannes.fries...@gmail.com wrote: The site looks very nice, I especially like the find real world examples functionality and the fact that it collects documentation for common non-core libraries as well. I made my own cheat sheet for private use over the past month or so, core functions only. It's at the 80% stage, I don't expect it will ever be 100%, but I have found it useful: http://faustus.webatu.com/clj-quick-ref.html Can I suggest omitting the Table of contents sidebar when printing? I've not tried printing the document to see how it looks, but removing the sidebar would be an essential starting point... Paul. -- 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
Re: ClojureDocs.org
I agree. The in-code function documentation serves its purpose but could be improved upon in a medium where space is at less of a premium. Bill Smith Austin, TX On Jul 10, 12:36 pm, James Reeves jree...@weavejester.com wrote: On 10 July 2010 15:06, Stuart Halloway stuart.hallo...@gmail.com wrote: (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. What about giving function documentation the same wiki behaviour that the examples have? Start off with the docstrings as the initial values, but allow people to update them. The web allows longer and better formatted documentation than a standard Clojure docstring (which needs to fit in a terminal). - James -- 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
Re: ClojureDocs.org
Hi,
Am 13.07.2010 um 14:26 schrieb j-g-faustus:
I made my own cheat sheet for private use over the past month or so,
core functions only. It's at the 80% stage, I don't expect it will
ever be 100%, but I have found it useful:
http://faustus.webatu.com/clj-quick-ref.html
Some comments after quickly skimming through:
next vs. rest: neither of those two „more“ idiomatic. They are just different.
next will realise the next element of the sequence (of any), while rest will
not. So in general you want rest, but sometimes next is useful, eg. in a loop:
(loop [s (seq s)] (when s (do-something) (recur (next s))).
Your comment on sequence is wrong: sequence and seq are – like rest and next –
two different things. It's not that sequence was the „old“ seq.
replicate is a relic from the time where repeat didn't have an optional n.
Your examples on transients are wrong. You have to capture the return value of
the bang! functions as you would do with the non-bang versions. That
(persistent! tm) works in your examples is an implementation detail.
condp has another form, which could be mentioned because it is not widely known:
user= (condp some [1 2 3]
#{2 4 6} : inc
#{3 5 7} : dec)
3
recur recurs not only to the function, but also to the same arity. So (fn ([a]
(println a)) ([a b] (recur (+ a b does not work.
extends? does check whether (extend ...) was called on a protocol with the
given type. This can be a Java class or something defined with with
deftype/defrecord. However for the latter not when the protocol methods where
specified inline.
io! is inside the transaction, but can be defined outside. (defn fn-with-io []
(io! (do-stuff))) . (dosync (fn-with-io)) - exception
You might want to mention #_ in the comments section. It is a reader macro
which drops the following read thing. Useful to comment out code without
messing with the parens.
user= [1 2 #_ 3]
[1 2]
In the require example: specifying :reload in an ns declaration smells.
You can also use :as with :use. (ns foo.bar (:use [frob.nicator :only
(defflogistionreactor) :as frobber])). Can be useful at times.
I don't like your use of '(quote lists) everywhere. Please use vectors. They
are the idiomatic answer of Clojure to quoted lists. Use quoted lists only
where it is interesting to distinguish the list from the vector, eg. in (vec
'(1 2 3)). (Related: if you find yourself quoting symbols, this means you
should use backquote because your are writing a macro or you should actually
use keywords.)
I really like your examples! They are simple, easy to understand, demonstrate
edge cases and focus on the thing being demonstrated. Two thumbs up.
Hope that helps.
Sincerely
Meikel
PS: I'm apologise if some this seems to be nit-picking.
--
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
Re: ClojureDocs.org
On 11 July 2010 12:05, Lukasz Urbanek resc...@gmail.com wrote: Looks very nice! Hoping for the categories to arrive to the core namespace. This really saves a lot of time for a clojure beginner like me. +1 Additionally, I'd prefer if the source was wasn't exposed by default (It's quite distracting when one is looking for the examples), some kind of source button that reveals it would be cool. +1 - I agree with others that people should be encouraged to program to the API, not the implementation. However sometimes its nice to be able to see the nitty gritty, so having a reveal source link would be great, without distracting from the more common case. R. -- 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
Re: ClojureDocs.org
On Jul 13, 8:37 pm, Paul Moore p.f.mo...@gmail.com wrote: Can I suggest omitting the Table of contents sidebar when printing? I've not tried printing the document to see how it looks, but removing the sidebar would be an essential starting point... Why would anyone want to print it? I occasionally print longer texts like specifications, but for reference material like Javadoc, ClojureDocs, the Ruby cheat sheet and this page, I think HTML is a far superior format due to links and browser search. And 40+ loose single sheets is a rather cumbersome package unless you have access to a book binder. But if at least two people feel that they would really like to print it out, I can skip the TOC on print. (Making it look _nice_ on paper is a whole different ballgame, then I'd have to look into pagination and page layouts, perhaps by converting to DocBook or LaTex. That's outside the scope of what I intended to do.) On Jul 13, 10:04 pm, Meikel Brandmeyer m...@kotka.de wrote: Some comments after quickly skimming through: ... PS: I'm apologise if some this seems to be nit-picking. Not at all, I'm still learning the language and happy to get the details clarified. The second form of condp and the #_ were omitted simply because I didn't know about them, thanks for the heads-up. For quoted lists, I take your point. For the sequence operations examples it was somewhat deliberate, in that a sequence is a very different datatype from a vector but pretty much the same as a list. I had a bug in some code that conj'ed elements onto a vector, but for some reason it would switch direction in the middle and start adding elements at the opposite end. It took me a while to figure out that it was because concat'ing two vectors doesn't return a vector. So I wanted to emphasize that using a sequence op on anything other than a list is also a conversion from one datatype to another. But I'll take another look, there may be better ways. Thanks for your comments, much appreciated. I'll include them with the next update. Sincerely, jf -- 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
Re: ClojureDocs.org
On Sun, Jul 11, 2010 at 4:10 PM, zkim zachary@gmail.com wrote: If you're willing to continue the discussion, I'd like to keep this going (maybe another thread?). As I'm writing this I'm getting the feeling that I'm not quite articulating my thoughts well, and I think further discussion will help me to flesh them out. Actually I was hoping it would spark a discussion with the maintainers and contributors of those projects. I haven't done any web development myself in years, I just know it always bothers me to hear It doesn't work or It's not ready about my own projects without more details. -Phil -- 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
Re: ClojureDocs.org
The site looks very nice, I especially like the find real world examples functionality and the fact that it collects documentation for common non-core libraries as well. I made my own cheat sheet for private use over the past month or so, core functions only. It's at the 80% stage, I don't expect it will ever be 100%, but I have found it useful: http://faustus.webatu.com/clj-quick-ref.html It is loosely inspired by the Ruby QuickRef http://www.zenspider.com/Languages/Ruby/QuickRef.html which I found tremendously useful. The experience has told me that good documentation is a lot of work, and I can see why people writing books want to get paid for their efforts :) So I appreciate the community aspect of your site. I expect that managing a community is just as much (or more) of a challenge than the technical aspects, but if you can get it working it can scale in a way that no private effort can. On Jul 11, 11:23 am, zkim zachary@gmail.com wrote: (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say show me 1.1) and on a per-var basis, reading the :added metadata. This is something I'd like to discuss in-depth on the new google group (http://groups.google.com/group/clojuredocsorg). It is something that I'd really like to see, but I haven't worked through the implementation details in my head (multiple versions stored per var vs. diffs stored, UI around this, etc). I would like to see this as well. In the short term I think the way the official doc does it, just listing the Since Clojure x.y metadata tag, works well enough. I can't really see the benefit of listing the source code for the function so prominently - in most cases I look up documentation to find out how to use a function, not how to implement it. I would suggest leaving it in a collapsed state initially. I am missing some form of logical grouping, like operations on vectors. Much of the benefit I get from using my own cheat sheet rather than the official documentation is that I can zoom in on for example the dozen or so operations that apply to agents (under Concurrency in my cheat sheet) rather than wading through hundreds of names that may or may not be relevant to what I am looking for. All in all a great initiative, and I hope there will be room for some level of grouping beyond alphabetically and by namespace. Regards jf -- 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
Re: ClojureDocs.org
On Jul 13, 12:25 am, j-g-faustus johannes.fries...@gmail.com wrote: I made my own cheat sheet for private use over the past month or so, core functions only. It's at the 80% stage, I don't expect it will ever be 100%, but I have found it useful: http://faustus.webatu.com/clj-quick-ref.html Looks like the hosting provider put my Clojure cheat sheet under review, I guess they found it suspicious... :) According to their website under review page, it should be available in a few hours. If not, and if anyone is interested in seeing it, I can probably find somewhere else to put it. jf -- 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
Re: ClojureDocs.org
Greg- I'd like to take the time to look over the post you linked in-depth before responding. but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. I'd like to be explicit here: I think the work that cgrand, mmcgrana, weavejester, brentonashworth, et al is amazing. I will be the first to get a big fat lambda tattoo on my forehead once the day comes that I can do all my web dev stuff in Clojure (please nobody hold me to this), but I'd like to wait till the web space matures a bit more before porting it over. The bottom line here is that I'd like to deliver the best possible user experience that I can, and as of right now that means a rails based solution. -Zack On Jul 9, 5:23 pm, Greg g...@kinostudios.com wrote: *argh*. well at least my email is now finally on the whitelist. What do you guys think of some of the ideas presented in the Solving Clojure's Documentation Problem Without Fragmentation thread? (Which I sent shortly after this thread started, but ended up being posted several hours later). https://groups.google.com/group/clojure/t/77fda1c7c95f5344 - Greg P.S. clojuredoc.org might be irrelevant if you guys choose to collaborate on the same project, but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) On Jul 9, 2010, at 7:05 PM, Justin Kramer wrote: An examples function for the REPL that pulls from the wiki: http://gist.github.com/470031 I'm sure something like it could be made for ClojureDocs.org once the API is in place. General comments on ClojureDocs.org: I think an important aspect of a collaborative tool like this is quality control. There needs to be people watching recent updates, making sure examples meet certain standards (formatted correctly, idiomatic, etc.). To that end, a complete list of recent updates (with diffs) to go along with the short list on the homepage would be really nice. Having a category-based outlines would also be nice. I have one here for clojure.core, adapted from the Cheatsheet: http://clojure-examples.appspot.com/clojure.core Feel free to nab it. FYI, I'll probably be implementing a mass export feature for the wiki, so you could write a script or something to automate an import. Awesome work, Zack. Justin On Jul 9, 2:25 pm, Alex Miller alexdmil...@yahoo.com wrote: I've actually been thinking about this exact same kind of site for a while now and I'm thrilled that I was too lazy to do it so that you could do it instead. :) One idea that I have that I think would be killer would be to provide an API to look up one your examples at the repl so I could do something like: = (use 'clojuredocs) = (example map) clojure.core/map (since 1.0) (map inc [1 2 3 4 5]) (2 3 4 5 6) There are of course many variants of some functions and different forms of use, so dealing with the best way to provide useful help without an overwhelming number of examples is tricky in the repl, but I think worth doing. Along with doc and source, I think example would be a killer addition to allowing you to explore the libraries from the comfort of your repl. Alex On Jul 9, 3:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and
Re: ClojureDocs.org
Heinz- first of all, great effort there :) having a place for clojure docs is awesome. Thanks, appreciated. 1) http://github.com/defn/walton - have a look at it, it might be a good way to fetch examples for functions where none are provided yet. I'll take a look. 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :) For now send me an email with a link to the repo, as well as any categorization suggestions you have for your lib. Ultimately I'd like to get clojuredocs.org to the point where you can enter a repo url into a web form and click 'add / update' (or maybe some code that watches a repo for updates). On Jul 10, 3:11 am, Heinz N. Gies he...@licenser.net wrote: Hi Zack, first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind: 1)http://github.com/defn/walton- have a look at it, it might be a good way to fetch examples for functions where none are provided yet. 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :) Regards, Heinz -- 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
Re: ClojureDocs.org
Shantanu- One suggestion -- consider providing a downloadable bundle for offline use as well. I believe there's an item up on the UserVoice page (http:// clojuredocs.uservoice.com/) keep an eye out for updates and comments there. -Zack On Jul 10, 3:29 am, Shantanu Kumar kumar.shant...@gmail.com wrote: This is great. One suggestion -- consider providing a downloadable bundle for offline use as well. Regards, Shantanu On Jul 10, 2:11 pm, Heinz N. Gies he...@licenser.net wrote: Hi Zack, first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind: 1)http://github.com/defn/walton-have a look at it, it might be a good way to fetch examples for functions where none are provided yet. 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :) Regards, Heinz -- 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
Re: ClojureDocs.org
Stu- (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later. That's +4 on this one by my tally, I'll pull the private vars. (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say show me 1.1) and on a per-var basis, reading the :added metadata. This is something I'd like to discuss in-depth on the new google group (http://groups.google.com/group/clojuredocsorg). It is something that I'd really like to see, but I haven't worked through the implementation details in my head (multiple versions stored per var vs. diffs stored, UI around this, etc). (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered. My first thought was to add some copy somewhere stating something to the effect of By adding content to this site you are allowing said content to be licensed under the EPL. My second thought was that I'm not a lawyer :). Jokes aside, I agree that this is an important matter, and while the exact mechanism to accomplish this is unclear to me, the direct effect is not: I'd like users to be able to freely add to, copy, and modify any user generated content to facilitate learning the Clojure language and its libraries. (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out. If I had to map this out right now I'd say the order of operations within the scope of this point would be (c), then (a), then (b), and all after locking down the provenance issue you outlined above. I believe Justin also had concerns around this issue, and I think the short answer is that the amount of pain is going to be inversely proportional to time, but I'm committed to taking whatever measures are necessary to ensure that the hard work that went into adding content to the site would not be lost. I'll start a thread over at the clojuredocs.org group to discuss this. Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. Sounds good, fix is up on the site. Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for editors to track new submissions, etc. I think a mix of community and 'admin / editor' influence would be great here. Initially I'd like to provide an RSS feed for additions / changes to examples and comments. It's difficult to guess down the line because of the nature of the other issues that are up in the air right now, but I think we'll figure something out. Thanks again for the feedback. I think you've framed some important discussions about clojuredocs.org, and community documentation in general. -Zack On Jul 10, 8:06 am, Stuart Halloway stuart.hallo...@gmail.com wrote: Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action. Here are a bunch of ideas, in no particular order: (1) Ease of contribution is huge, andhttp://clojuredocs.orglooks good on this front. Stick to it. (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later. (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say show me 1.1) and on a per-var basis, reading the :added metadata. (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered. (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out. (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. (7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up
Re: ClojureDocs.org
On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil -- 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
Re: ClojureDocs.org
Looks very nice! Hoping for the categories to arrive to the core namespace. This really saves a lot of time for a clojure beginner like me. Additionally, I'd prefer if the source was wasn't exposed by default (It's quite distracting when one is looking for the examples), some kind of source button that reveals it would be cool. -- 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
Re: ClojureDocs.org
On Sun, Jul 11, 2010 at 8:14 AM, Phil Hagelberg p...@hagelb.org wrote: On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil It sounded to me like he was only saying that he's more familiar with Ruby/Rails than he is with Clojure. It seemed like it was a question of 'time to finish and tweak' that's shortest for him if he wrote it in Ruby/Rails. Maybe this is a good opportunity to be able to compare two implementations side-by-side. His excellent solution with one written in Clojure that produces the same-ish website. -Rich -- 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
Re: ClojureDocs.org
Phil- A little background on my clojure web experience: I've got a intranet web tool written using ring / enlive / moustache (system health / monitoring for a personal project) as well as dabbled in compojure before the 0.4.0 rev, and more recently I've been looking at sandbar / carte. The timeframe for which I last took a serious look at Clojure web technologies was April - May of this year (2010). I'd say there were four main reasons why I chose to use rails over a Clojure based solution: 1. Personal ease of feature implementation: This is part personal past experience, part community support. I have some experience in rails, and other rails-like frameworks. As far as community goes, every problem (except the Passenger question mark problem I'm currently having) there was a googleable solution that I found, or at least a discussion that I could use to learn about the problem I was having, consensuses on best practices, etc. 2. Persistence. For that monitoring intranet app I mentioned above I'm using clojure.contrib.sql to make one-off connections to some relatively simple schemas (log entries, no relations). A moderately complex schema would have throw me for a loop using clojure. 3. Sessions using ring handlers. These were a problem for me, but I think my handler mental model is broken. 4. Ecosystem. Tons of gems, plugins. Great for getting the broad strokes down. If you're willing to continue the discussion, I'd like to keep this going (maybe another thread?). As I'm writing this I'm getting the feeling that I'm not quite articulating my thoughts well, and I think further discussion will help me to flesh them out. Again, I'm really excited about the amazing progress that's been made in the Clojure web space (even just since May). It's a tough problem to get right, and I'm definitely willing to help those that have taken up this difficult challenge any way I can. -Zack On Jul 11, 8:14 am, Phil Hagelberg p...@hagelb.org wrote: On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil -- 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
Re: ClojureDocs.org
Lukasz- Hoping for the categories to arrive to the core namespace. This really saves a lot of time for a clojure beginner like me. The way Justin did this is great (http://clojure-examples.appspot.com/ clojure.core). I'm hoping to add this in the near future. Additionally, I'd prefer if the source was wasn't exposed by default (It's quite distracting when one is looking for the examples), some kind of source button that reveals it would be cool. There have been several other comments on clarifying the visual style of the var pages. I'm going to roll this suggestion into those on the UserVoice page. -Zack On Jul 11, 5:05 am, Lukasz Urbanek resc...@gmail.com wrote: Looks very nice! Hoping for the categories to arrive to the core namespace. This really saves a lot of time for a clojure beginner like me. Additionally, I'd prefer if the source was wasn't exposed by default (It's quite distracting when one is looking for the examples), some kind of source button that reveals it would be cool. -- 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
Re: ClojureDocs.org
Rich- It sounded to me like he was only saying that he's more familiar with Ruby/Rails than he is with Clojure. Correct. I think it was a fair question, and I'm happy to provide insights into my decision making process. -Zack On Jul 11, 12:37 pm, Richard Lyman richard.ly...@gmail.com wrote: On Sun, Jul 11, 2010 at 8:14 AM, Phil Hagelberg p...@hagelb.org wrote: On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil It sounded to me like he was only saying that he's more familiar with Ruby/Rails than he is with Clojure. It seemed like it was a question of 'time to finish and tweak' that's shortest for him if he wrote it in Ruby/Rails. Maybe this is a good opportunity to be able to compare two implementations side-by-side. His excellent solution with one written in Clojure that produces the same-ish website. -Rich -- 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
Re: ClojureDocs.org
We use Rails for all our GUIs, we need simple CRUD most of the time and we ActiveScaffold. Most of our controllers are less than 70 lines and we seldom write forms. We use the ActiveScaffold partial forms almost every were sometimes custpmizing them. Clojure Web Frameworks are not there yet. We monitor the situation however and will change our mind as soon as it looks promiding... Zack, keep the focus on the problem to solve :))) Luc P. Sent from my iPod On 2010-07-11, at 19:31, zkim zachary@gmail.com wrote: Rich- It sounded to me like he was only saying that he's more familiar with Ruby/Rails than he is with Clojure. Correct. I think it was a fair question, and I'm happy to provide insights into my decision making process. -Zack On Jul 11, 12:37 pm, Richard Lyman richard.ly...@gmail.com wrote: On Sun, Jul 11, 2010 at 8:14 AM, Phil Hagelberg p...@hagelb.org wrote: On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph- based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil It sounded to me like he was only saying that he's more familiar with Ruby/Rails than he is with Clojure. It seemed like it was a question of 'time to finish and tweak' that's shortest for him if he wrote it in Ruby/Rails. Maybe this is a good opportunity to be able to compare two implementations side-by-side. His excellent solution with one written in Clojure that produces the same-ish website. -Rich -- 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
Re: ClojureDocs.org
As a Clojure novice I'm happy to see the documentation side of the Clojure ecosystem growing regardless of the stack used for a doc site. Having a resource like a user-edited php.net will be a great help. I am excited about submitting a few examples of my own. On Jul 11, 9:14 am, Phil Hagelberg p...@hagelb.org wrote: On Sat, Jul 10, 2010 at 11:23 PM, zkim zachary@gmail.com wrote: but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) I'm inclined to move forward with the Ruby / Rails for now. The reason I went with rails is that (in my experience) none of the clojure web libraries are mature enough to do something like clojuredocs as quickly and easily as I personally would be able to do in rails. Could you provide details about what it was specifically that you found was lacking? -Phil -- 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
Re: ClojureDocs.org
Hi Zack, first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind: 1) http://github.com/defn/walton - have a look at it, it might be a good way to fetch examples for functions where none are provided yet. 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :) Regards, Heinz -- 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
Re: ClojureDocs.org
This is great. One suggestion -- consider providing a downloadable bundle for offline use as well. Regards, Shantanu On Jul 10, 2:11 pm, Heinz N. Gies he...@licenser.net wrote: Hi Zack, first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind: 1)http://github.com/defn/walton- have a look at it, it might be a good way to fetch examples for functions where none are provided yet. 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :) Regards, Heinz -- 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
Re: ClojureDocs.org
This is GREAT!!! I love the way you have opened it up for community participation. Robert On Jul 9, 4:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
On 9 July 2010 21:06, Tom Faulhaber tomfaulha...@gmail.com wrote: Quick thought: You probably don't want to include private vars. Seconded. It's a little confusing seeing private vars and macros in the API docs! Other than that, this looks excellent. I'm signing up as I write this. - James -- 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
Re: ClojureDocs.org
Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action. Here are a bunch of ideas, in no particular order: (1) Ease of contribution is huge, and http://clojuredocs.org looks good on this front. Stick to it. (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later. (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say show me 1.1) and on a per-var basis, reading the :added metadata. (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered. (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out. (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. (7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for editors to track new submissions, etc. Thanks again! Stu Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up with http://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example, http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move from http://clojuredocs.org/clj-ssh/clj-ssh.core/file-path to http://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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 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,
Re: ClojureDocs.org
On 10 July 2010 15:06, Stuart Halloway stuart.hallo...@gmail.com wrote: (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. What about giving function documentation the same wiki behaviour that the examples have? Start off with the docstrings as the initial values, but allow people to update them. The web allows longer and better formatted documentation than a standard Clojure docstring (which needs to fit in a terminal). - James -- 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
Re: ClojureDocs.org
Zack if you need help with this Rail app let us now. We can give you a hand, the wish list keeps growing :))) Luc P. Sent from my iPod On 2010-07-09, at 15:07, zkim zachary@gmail.com wrote: Hi Justin, thanks again for the go-ahead to pull examples from http://clojure-examples.appspot.com. Zack, you had mentioned you planned to keep the source of your site proprietary -- is that set in stone? Definitely not set in stone. As far as the site goes there's not much Clojure going on there (rails / mysql), and I'd rather keep that part closed for now so I can concentrate on moving from alpha to beta, adding features, and fixing bugs. The analyzer, which pulls metadata / source from libraries, and inserts it into the database is a different story. Other than the fact that it's extremely hackish, nothing's really stopping me from EPLing it in the near future. You also mentioned an API / export process, which I think is a great idea. This would allow examples to be easily exported to prevent vendor lock-in. -Zack On Jul 9, 12:44 pm, Justin Kramer jkkra...@gmail.com wrote: I've told Zack that he is free to pull any examples from the wiki for use on his site. I don't know about collaboration beyond that. The wiki is open source and written in Clojure; anyone is free to contribute/fork. At least one person has expressed interest in making code contributions. Zack, you had mentioned you planned to keep the source of your site proprietary -- is that set in stone? Justin On Jul 9, 12:21 pm, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
http://gist.github.com/470031 I'm sure something like it could be made for ClojureDocs.org once the API is in place. Nice, looks pretty straightforward. I think an important aspect of a collaborative tool like this is quality control. To that end, a complete list of recent updates (with diffs) to go along with the short list on the homepage would be really nice. Agreed. I'd like to have an in depth discussion around this issue, and what potential solutions would look like, so I've set up google group (http://groups.google.com/group/clojuredocsorg). I'll be seeding this form with a couple of posts later tonight revolving around what I feel are some core issues that are very important to get right, and therefore require community facing discussion. Having a category-based outlines would also be nice. I have one here for clojure.core, adapted from the Cheatsheet: http://clojure-examples.appspot.com/clojure.core Thanks, this would be very nice to have. FYI, I'll probably be implementing a mass export feature for the wiki, so you could write a script or something to automate an import. I'll keep an eye out for this. -Zack On Jul 9, 5:05 pm, Justin Kramer jkkra...@gmail.com wrote: An examples function for the REPL that pulls from the wiki: http://gist.github.com/470031 I'm sure something like it could be made for ClojureDocs.org once the API is in place. General comments on ClojureDocs.org: I think an important aspect of a collaborative tool like this is quality control. There needs to be people watching recent updates, making sure examples meet certain standards (formatted correctly, idiomatic, etc.). To that end, a complete list of recent updates (with diffs) to go along with the short list on the homepage would be really nice. Having a category-based outlines would also be nice. I have one here for clojure.core, adapted from the Cheatsheet: http://clojure-examples.appspot.com/clojure.core Feel free to nab it. FYI, I'll probably be implementing a mass export feature for the wiki, so you could write a script or something to automate an import. Awesome work, Zack. Justin On Jul 9, 2:25 pm, Alex Miller alexdmil...@yahoo.com wrote: I've actually been thinking about this exact same kind of site for a while now and I'm thrilled that I was too lazy to do it so that you could do it instead. :) One idea that I have that I think would be killer would be to provide an API to look up one your examples at the repl so I could do something like: = (use 'clojuredocs) = (example map) clojure.core/map (since 1.0) (map inc [1 2 3 4 5]) (2 3 4 5 6) There are of course many variants of some functions and different forms of use, so dealing with the best way to provide useful help without an overwhelming number of examples is tricky in the repl, but I think worth doing. Along with doc and source, I think example would be a killer addition to allowing you to explore the libraries from the comfort of your repl. Alex On Jul 9, 3:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion-
Re: ClojureDocs.org
I took a first look and I have to say that the idea is genius and I love what you put up together this far. It is difficult to keep up with what's happening in the Clojure world, and this kind of central place to keep track of things was needed. The examples are also a strong point. I hope the site will grow with many people's contributions. Victor On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up with http://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example, http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move from http://clojuredocs.org/clj-ssh/clj-ssh.core/file-path to http://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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.comclojure%2bunsubscr...@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
Re: ClojureDocs.org
On Fri, Jul 9, 2010 at 2:32 AM, zkim zachary@gmail.com wrote: Hi All, Questions / thoughts? -Zack Hi Zack, First off, I think it looks great, and it definitely seems useful when trying to find an example of a particular API call. Few suggestions: 1. The headers for each section (Doc, Source, Example(s)) don't differentiate themselves from the regular doc text enough, maybe bold/underline/color them to make them show up more? 2. The links to the source code should link to http://github.com/clojure/clojure, I believe the richhickey clojure repo has been transitioned there. 3. I know non-confirmation logins are really nice, but should the site attract any spammers, you may want to look at adding an email account confirmation (since spammers could go nuts adding comments to pages). Looks awesome, hope it gets some love from the Clojure community. - Lee -- 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
Re: ClojureDocs.org
On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
Having contributed a lot of examples to clojure-examples.appspot.com this week, I agree that it would be a shame to duplicate efforts. On Jul 9, 11:21 am, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
It's a great idea, and the site looks very good. Two suggestions: 1. Move examples section above source code section 2. Add OpenID sign in support. Personally I'm instantly repelled by sites asking me to create another account/password. And I'm sure I'm not alone. Stackoverflow.com is a great example of how effortless it could be to register. - Dmitry On Jul 9, 1:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
I've actually been thinking about this exact same kind of site for a while now and I'm thrilled that I was too lazy to do it so that you could do it instead. :) One idea that I have that I think would be killer would be to provide an API to look up one your examples at the repl so I could do something like: = (use 'clojuredocs) = (example map) clojure.core/map (since 1.0) (map inc [1 2 3 4 5]) (2 3 4 5 6) There are of course many variants of some functions and different forms of use, so dealing with the best way to provide useful help without an overwhelming number of examples is tricky in the repl, but I think worth doing. Along with doc and source, I think example would be a killer addition to allowing you to explore the libraries from the comfort of your repl. Alex On Jul 9, 3:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
I've told Zack that he is free to pull any examples from the wiki for use on his site. I don't know about collaboration beyond that. The wiki is open source and written in Clojure; anyone is free to contribute/fork. At least one person has expressed interest in making code contributions. Zack, you had mentioned you planned to keep the source of your site proprietary -- is that set in stone? Justin On Jul 9, 12:21 pm, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
Quick thought: You probably don't want to include private vars. On Jul 9, 1:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
On Fri, Jul 9, 2010 at 2:32 AM, zkim zachary@gmail.com wrote: Hi All, Questions / thoughts? -Zack Hi Zack, First off, I think it looks great, and it definitely seems useful when trying to find an example of a particular API call. Few suggestions: 1. The headers for each section (Doc, Source, Example(s)) don't differentiate themselves from the regular doc text enough, maybe bold/underline/color them to make them show up more? 2. The links to the source code should link to http://github.com/clojure/clojure, I believe the richhickey clojure repo has been transitioned there. 3. I know non-confirmation logins are really nice, but should the site attract any spammers, you may want to look at adding an email account confirmation (since spammers could go nuts adding comments to pages). Looks awesome, hope it gets some love from the Clojure community. - Lee -- 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
Re: ClojureDocs.org
Thanks all for your kind words. As to the specifics: The headers for each section (Doc, Source, Example(s)) don't differentiate themselves from the regular doc text enough, maybe bold/underline/color them to make them show up more? I'd agree, I think the visual styling of the page will change a lot in the near future based on feedback, for now I'll add underlining. The links to the source code should link to http://github.com/clojure/clojure, I believe the richhickey clojure repo has been transitioned there. Will update. I know non-confirmation logins are really nice, but should the site attract any spammers, you may want to look at adding an email account confirmation (since spammers could go nuts adding comments to pages). This is strictly for alpha, I'm currently going back and forth between signups confirmed through email, or recaptcha (or both), but rounding out the sign-up / login process is high on my list. This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. Having contributed a lot of examples to clojure-examples.appspot.com this week, I agree that it would be a shame to duplicate efforts. I've been talking with Justin, and he's allowed me to pull examples from his site (as well as given some great feedback). I'm definitely all for a collaborative effort. Thanks, Zack. On Jul 9, 10:30 am, .Bill Smith william.m.sm...@gmail.com wrote: Having contributed a lot of examples to clojure-examples.appspot.com this week, I agree that it would be a shame to duplicate efforts. On Jul 9, 11:21 am, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
I've put these suggestions up on the UserVoice page, I believe I got all of them, but if I missed yours please add it yourself or let me know. Dimitri: I share your frustrations with having to remember yet another login / password. Other than minor cosmetic fixes, improving the user signup / login experience is at the top of my list. Alex: Example lookup from the REPL would be awesome. As of now this is a bit lower on the list until things stabilize around the site. Side note: My responses don't seem to be showing up right away on the mailing list, so they may appear out of order. -- 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
Re: ClojureDocs.org
Hi Justin, thanks again for the go-ahead to pull examples from http://clojure-examples.appspot.com. Zack, you had mentioned you planned to keep the source of your site proprietary -- is that set in stone? Definitely not set in stone. As far as the site goes there's not much Clojure going on there (rails / mysql), and I'd rather keep that part closed for now so I can concentrate on moving from alpha to beta, adding features, and fixing bugs. The analyzer, which pulls metadata / source from libraries, and inserts it into the database is a different story. Other than the fact that it's extremely hackish, nothing's really stopping me from EPLing it in the near future. You also mentioned an API / export process, which I think is a great idea. This would allow examples to be easily exported to prevent vendor lock-in. -Zack On Jul 9, 12:44 pm, Justin Kramer jkkra...@gmail.com wrote: I've told Zack that he is free to pull any examples from the wiki for use on his site. I don't know about collaboration beyond that. The wiki is open source and written in Clojure; anyone is free to contribute/fork. At least one person has expressed interest in making code contributions. Zack, you had mentioned you planned to keep the source of your site proprietary -- is that set in stone? Justin On Jul 9, 12:21 pm, David Nolen dnolen.li...@gmail.com wrote: On Fri, Jul 9, 2010 at 4:32 AM, zkim zachary@gmail.com wrote: Questions / thoughts? -Zack This is great. I think the main thing is not duplicating effort. This and clojure-examples.appspot.com should really join forces. David -- 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
Re: ClojureDocs.org
On 9 July 2010 09:32, zkim zachary@gmail.com wrote: Questions / thoughts? Looks really good to me. Could you display the version numbers for Clojure and the libraries that the site covers? Gavin -- 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
Re: ClojureDocs.org
Beautiful. I think this should become the official community place for Clojure docs. Now who wants to integrate my :examples defn attribute code :) -John On Jul 9, 4:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojuredocs.org/v/1484. I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
Tom- I kind of went back and forth on this. Originally I only parsed out public vars, but in a couple of instances I found that when tracing through some code I would hit on private vars. Perhaps a solution where private vars are hidden from normal flow (browsing and searching) unless explicitly included by the user? -Zack On Jul 9, 2:06 pm, Tom Faulhaber tomfaulha...@gmail.com wrote: Quick thought: You probably don't want to include private vars. On Jul 9, 1:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
An examples function for the REPL that pulls from the wiki: http://gist.github.com/470031 I'm sure something like it could be made for ClojureDocs.org once the API is in place. General comments on ClojureDocs.org: I think an important aspect of a collaborative tool like this is quality control. There needs to be people watching recent updates, making sure examples meet certain standards (formatted correctly, idiomatic, etc.). To that end, a complete list of recent updates (with diffs) to go along with the short list on the homepage would be really nice. Having a category-based outlines would also be nice. I have one here for clojure.core, adapted from the Cheatsheet: http://clojure-examples.appspot.com/clojure.core Feel free to nab it. FYI, I'll probably be implementing a mass export feature for the wiki, so you could write a script or something to automate an import. Awesome work, Zack. Justin On Jul 9, 2:25 pm, Alex Miller alexdmil...@yahoo.com wrote: I've actually been thinking about this exact same kind of site for a while now and I'm thrilled that I was too lazy to do it so that you could do it instead. :) One idea that I have that I think would be killer would be to provide an API to look up one your examples at the repl so I could do something like: = (use 'clojuredocs) = (example map) clojure.core/map (since 1.0) (map inc [1 2 3 4 5]) (2 3 4 5 6) There are of course many variants of some functions and different forms of use, so dealing with the best way to provide useful help without an overwhelming number of examples is tricky in the repl, but I think worth doing. Along with doc and source, I think example would be a killer addition to allowing you to explore the libraries from the comfort of your repl. Alex On Jul 9, 3:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel free to contact me directly through email. Questions / thoughts? -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
Re: ClojureDocs.org
*argh*. well at least my email is now finally on the whitelist. What do you guys think of some of the ideas presented in the Solving Clojure's Documentation Problem Without Fragmentation thread? (Which I sent shortly after this thread started, but ended up being posted several hours later). https://groups.google.com/group/clojure/t/77fda1c7c95f5344 - Greg P.S. clojuredoc.org might be irrelevant if you guys choose to collaborate on the same project, but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details) On Jul 9, 2010, at 7:05 PM, Justin Kramer wrote: An examples function for the REPL that pulls from the wiki: http://gist.github.com/470031 I'm sure something like it could be made for ClojureDocs.org once the API is in place. General comments on ClojureDocs.org: I think an important aspect of a collaborative tool like this is quality control. There needs to be people watching recent updates, making sure examples meet certain standards (formatted correctly, idiomatic, etc.). To that end, a complete list of recent updates (with diffs) to go along with the short list on the homepage would be really nice. Having a category-based outlines would also be nice. I have one here for clojure.core, adapted from the Cheatsheet: http://clojure-examples.appspot.com/clojure.core Feel free to nab it. FYI, I'll probably be implementing a mass export feature for the wiki, so you could write a script or something to automate an import. Awesome work, Zack. Justin On Jul 9, 2:25 pm, Alex Miller alexdmil...@yahoo.com wrote: I've actually been thinking about this exact same kind of site for a while now and I'm thrilled that I was too lazy to do it so that you could do it instead. :) One idea that I have that I think would be killer would be to provide an API to look up one your examples at the repl so I could do something like: = (use 'clojuredocs) = (example map) clojure.core/map (since 1.0) (map inc [1 2 3 4 5]) (2 3 4 5 6) There are of course many variants of some functions and different forms of use, so dealing with the best way to provide useful help without an overwhelming number of examples is tricky in the repl, but I think worth doing. Along with doc and source, I think example would be a killer addition to allowing you to explore the libraries from the comfort of your repl. Alex On Jul 9, 3:32 am, zkim zachary@gmail.com wrote: Hi All, I'll try to keep this short. I've gotten a lot out of Clojure: I can honestly say that learning this language, and being part of this community has made me a better, happier developer, and I wanted to give something back. One of the pain points that I encountered when learning the language was a lack of examples specific to the individual functions I was trying to wrap my head around at any given time. So I took a whack at the problem, and came up withhttp://clojuredocs.org. It's a site that (I'm hoping) will fill this need by providing a centralized examples database, along with solid search capabilities across both core and third party libraries (core being the focus). Implementation: ClojureDocs.org is a rails site backed by MySQL, along with some clojure code to pull the namespaces / metadata / source and dump them into the database. Highlights: 1. Documentation and source for Clojure core, contrib, and a few third party libraries (random selection out of what I'm personally familiar with, and whatever was on the github trends page that day). 2. Search for a var across the whole ecosystem or in a specific library. 3. Per var wiki-style examples section. 4. Per var comments section. 5. Per var vars-in-this-var and this-var-used-in section (my personal favorite). Looking for a real-world example of a specific function? This is for you. For example,http://clojuredocs.org/v/1978, just below the source section. Lowlights: 1. Ugly URLs! There's a problem in the way that URLs with encoded question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure I've got an email out to the Phusion Passenger mailing list (http://groups.google.com/group/phusion- passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any experience in this area drop me a line. 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug in the import process. 3. General rough-around-the-edges-ness. I'm treating this as an alpha, and I'd really like feedback as to: a. How useful this would be to the community. b. Specific likes / dislikes about this alpha release. c. Feature requests. I've set up a feedback mechanism directly through the site (User Voice), which allows voting on specific posts. I'm also considering setting up a google group for general discussion. Feel
Re: ClojureDocs.org
Hi, Am 09.07.2010 um 23:47 schrieb zkim: I kind of went back and forth on this. Originally I only parsed out public vars, but in a couple of instances I found that when tracing through some code I would hit on private vars. I'm suspicious of showing source code to the reader with everything more than a small quite nondescript link. The contract is the docstring. Looking at the code might be interesting but non-helpful. You start relying on implementation details, while these might change at any time (eg. introduction of transients, etc.). I would *not* show the source code and I would *not* document private vars. They are not part of the contract and should not show up in public API documentation. Sincerely Meikel -- 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
