

Clojure Grimoire: an up-to-date ClojureDocs alternative - jgrodziski
http://grimoire.arrdem.com/

======
Terretta
I've been using Clojure Cheatsheets from Andy Fingerhut at
[http://jafingerhut.github.io](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](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](http://jafingerhut.github.io) \- various
versions of cheetsheet

[http://grimoire.arrdem.com](http://grimoire.arrdem.com) \- cheatsheet + docs

Or go here for the PDFs:

[https://github.com/jafingerhut/clojure-
cheatsheets/tree/mast...](https://github.com/jafingerhut/clojure-
cheatsheets/tree/master/pdf)

------
stevepike
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...](http://clojure.github.io/clojure/clojure.core-
api.html#clojure.core/assoc) and
[http://grimoire.arrdem.com/1.6.0/clojure.core/assoc/](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](http://kapeli.com/dash))!

~~~
rdmckenzie
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/](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/](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.

~~~
stevepike
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).

------
rdmckenzie
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.

------
dj-wonk
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...](https://github.com/xpe/clj-
destruct/blob/master/src/destruct/core.clj)

~~~
rdmckenzie
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.

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

------
janerik
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.

~~~
threeseed
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.

------
daGrevis
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.

------
th0ma5
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?

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

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

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

~~~
rdmckenzie
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

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

