Clojure Grimoire: an up-to-date ClojureDocs alternative | Hacker News Reader

Clojure Grimoire: an up-to-date ClojureDocs alternative

grimoire.arrdem.com

163 pointsjgrodziski21 comments

I've been using Clojure Cheatsheets from Andy Fingerhut at http://jafingerhut.github.io and particularly happy with the color PDF versions (link below).

Andy actively keeps up with issues and pulls to make sure the output stays well formatted for easy printing on both US Letter and A4 as well as of course an HTML online reference.

His cheatsheets traditionally linked to ClojureDocs, but just yesterday Andy accepted a pull request to merge in targeting Grimoire, while Reid mashed up Andy's work into the Grimoire homepage:

    arrdem commented 2 days ago
    Thank you. I'm working on mashing the Grimoire linked version up to be
    part of 0.2.0's homepage :D
    …

    On 07/11/2014 02:52 PM, Andy Fingerhut wrote:

     Thanks! I'll try generating HTML and PDF cheat sheets with these
     changes, and if everything goes well I will publish Grimoire-linked
     HTML versions at http://jafingerhut.github.io and announce on the
     Google group.

-- https://github.com/jafingerhut/clojure-cheatsheets/pull/10

I appreciate clojure community collaboration and it's great these two projects sync'd up:

http://jafingerhut.github.io - various versions of cheetsheet

http://grimoire.arrdem.com - cheatsheet + docs

Or go here for the PDFs:

https://github.com/jafingerhut/clojure-cheatsheets/tree/mast...

This is really awesome, thanks for building it. I was just working on a toy clojurescript project yesterday and while clojuredocs is very useful it's sad it hasn't been updated in forever. I've found examples to be incredibly helpful in composing functional-style code. For instance, compare assoc: http://clojure.github.io/clojure/clojure.core-api.html#cloju... and http://grimoire.arrdem.com/1.6.0/clojure.core/assoc/.

The architecture choice OP made is clever - a completely static page linking to github for the CMS part. Would you consider writing a server-backed version at some point in the future? Clojuredocs was originally written in rails and is being re-written in clojure, but that's going slowly. I would absolutely love to see a well-written clojure backend for this type of site as a reference. I've been really enjoying using clojure for standalone things, but I can't yet imagine how I'd build a web server with all the production features something like rails gives you ootb (asset compilation, csrf, sessions, db connections, orm, testing w. transaction-based fixtures, etc).

Now if I could just integrate this with dash (http://kapeli.com/dash)!

For reference, the Clojure rewrite is https://github.com/zk/clojuredocs and is hosted at http://clojuredocs.herokuapp.com/

I'd love to help with building a backend, if the author or someone else decides to go that way. Just recently finished rewriting my blog in Clojure, complete with csrf protection, db, sessions, and a bunch of shinies as well.

I'd love to read a blog post about your experience writing that, and to see the code!

Oh shucks, now I will just have to finish the blog post and publish it. Thanks!

Author here. After maintaining a blog built around a "real" CMS, and a "real" CMS that I built myself, I'll say that my existing blog is built atop Jekyll and Git, the same stack I chose for Grimoire. It's simply the most basic thing that could possibly work, and it doesn't demand that I run a JVM on my inexpensive DigitalOcean instance. For all that I enjoy using Clojure, a "real" Ring server with a "real" database backend simply doesn't add anything to this project beyond complicating it further. As such I don't expect that a database rewrite of Grimoire is on the cards for some time to come.

To "how you build such a site in Clojure" the answer is that the entire Clojure ecosystem shies away from monolithic web frameworks and prepackaged solutions ala rails. Instead, Clojure libraries tend to pick a single feature or some small set of fetures, cover them well, expose a simple API and make composition trivial rather than trying to solve all possible problems.

Dash integration... Dash only makese sense for languages for which the documentation isn't trivially introspected such as Java. Clojure has the clojure.repl library (http://grimoire.arrdem.com/1.6.0/clojure.repl/) which is designed to solve this problem by exposing Clojure documentation to users in their interactive development (REPL) sessions. As I explain at some length in the Grimoire announcement post (http://arrdem.com/2014/07/12/of_mages_and_grimoires/) Grimoire seeks to fill a fumdimentally different niche than Dash. Clojure already has docs, and those docs are already handy for users aware of clojure.repl. Grimoire seeks to solve the problem of documenting the various ins and outs of the standard library which do _not_ appear in the official Clojure docs and which are currently spread out across any number of other low PageRank score community sites.

I definitely wasn't trying to say this project would be better served by a "real" CMS, just that I'd like to see how someone would put one together. I've heard the idea of your second paragraph repeated in a bunch of places, and it speaks to me on an intellectual level, but I'd like to read through examples of non-trivial apps to put it in concrete terms.

About dash - presumably users will want your content inside whatever editing environment they have going (I know I do!). I find myself jumping between the built-in Emacs thing for clojure (shows function signatures in the minibuffer, let's you jump to official docs and source in other buffers) and dash for ruby (pretty html rendering, loads all my library docs).

Author here. Holy cow. Thanks for all the kind words guys! I'm primarily a back end dev interested in hardware, compilers and operating systems. As a long time HN reader I can't begin to express how amazing it is that a my first "real" web service which I started less than a week ago made the front page.

I hope that for those Clojure users among you Grimoire proves a useful resource and I welcome any feedback or other commentary you may have on the site and its usability. Stay tuned, there's plenty more in the works from me and I'm reading the feedback with interest.

Cool. One limitation I've seen is a lack of destructuring examples. So, for those who get a little hung up with some of the more complicated destructuring permutations, I made a walkthrough here: https://github.com/xpe/clj-destruct/blob/master/src/destruct...

Author here. I'm definitely aware that there are many pitfalls to Clojure than just the standard library docs. There's an open issue for adding a syntax guide and a macro guide, I'd be delighted to add a destructuring guide.

Great! Do you think my example code (linked above) would be a good fit? It is mostly example-based.

Neat. Apart from the bright red color of the search field, it's great! I just started playing around a little with Clojure and having the docs right at your fingertips definitely helps.

Agreed. It should just change the text colour and there is also a bug where if the text field is blank it still shows as red. Otherwise brilliant site.

Looks great! Especially I like the clean design.

I'm waiting for DevDocs.io support for Clojure thought because there's nothing better than all docs in one place.

Have to use landscape in Chrome on Android. This is really really great!! I have a friend that knows C and wonders how the heck Clojure actually does anything. I've tried but anyone have any good links?

Very neat. Particularly like that you've included instructions for running locally. Kudos.

Ah, thank you. I get frustrated by clojuredocs out of dateness, but I do like their comments.

Fantastic, also has much better examples than clojuredocs.org!

Author here: It's funny that you say this because as of right now there is only one example on Grimoire that isn't on Clojuredocs :P

Haha, that's surprising. Maybe the better presentation makes the examples look more plentiful.

Reply on news.ycombinator.com