Cider: [FEATURE REQUEST] Add suuport for https://clojuredocs.org

[NightMachinary]

https://clojuredocs.org seems better than conj.io (it has more examples). Perhaps allow different backends for grimoire? Or add this as an alternative?

[bbatsov]

Grimoire is conj.io. :-)

I was thinking of adding some integration with clojuredocs.org, but I never got to doing this. Technically it's very easy to do, but requires time I'm pretty short on these days.

[NightMachinary]

@bbatsov Now that we are on it, making cider-javadoc not shell out to a browser is also good.

[TimoFreiberg]

Currently implementing this, I'm not sure I understand the regexp

"\\(\\`_\\)\\|\\(_\\'\\)"

at https://github.com/clojure-emacs/cider/blob/master/cider-grimoire.el#L51
The underscore is not a special character, right?
So it matches (and therefore removes) any occurrences of `_ and _'?

I didn't actually find any such symbols on grimoire or clojuredocs so I couldn't test this assumption.

Fun fact: I just found out that I can use single backticks in inline code blocks if I delimit those blocks with 2 backticks each. :1st_place_medal:

[camdez]

@TimoFreiberg You're spot-on that _ is not a special character, but \` and \' have special significance—they match the beginning of the string being matched against. Rather like ^ and $ but string-oriented rather than line-oriented (the difference only appears when the string in question has embedded newlines).

Emacs' quoting makes things a bit noisy but it's conceptually almost the same as this:

$ echo "_FOO_BAR_" | sed -E 's/(^_)|(_$)//g'
FOO_BAR

Alternately, simple answer: it removes an underscore character from the beginning and end of the string, if present.

While you're in there, the docstring could use a little updating. ;)

[TimoFreiberg]

Thanks for the explanation!
Yeah, I'm keeping an eye on the documentation as well :)

[TimoFreiberg]

I think some discussion about what to actually do here is required.

@NightMachinary: Your request sounds like you want to be able to customize a variable that makes cider-grimoire and cider-grimoire-web call clojuredocs.org instead of conj.io, right?

I attempted that and I have some problems with cider-grimoire, the function that shows the plaintext response in a buffer.
Namely, clojuredocs.org doesn't seem to offer plaintext responses, so the minibuffer gets filled with html which is completely unreadable.

I looked around the clojuredocs site and codebase a bit and didn't find any mentions of an API/a way to get markdown formatted pages.

The only possibility I see would be to offer a clojuredocs-web-lookup function as an alternative function to grimoire.
But adding clojuredocs as a grimoire replacement is not possible right now.

Stopping progress for now until this is resolved.

[bbatsov]

I really don't think that we should make cider-grimoire configurable, as it's meant to be used with the grimoire. We should probably just provide a similar interface (or better) for clojuredocs.

Similar functionality for clojuredocs can probably be developed with https://github.com/dakrone/clojuredocs-client

Namely, clojuredocs.org doesn't seem to offer plaintext responses, so the minibuffer gets filled with html which is completely unreadable.

Guess you can just render it with eww if you want to go down this route, but plain text would certainly be better.

[bbatsov]

On a related note - at some point I had decided it was probably going to be better to build some api for dealing with such doc services as part of cider-nrepl or orchard, but I never got to doing so.

[vemv]

While grimoire doesn't have a lot of traction, it has the architectural advantage of storing is data as a jar: https://github.com/clojure-grimoire/datastore

That can enable offline usage and faster / more reliable responses.

cider-grimoire doesn't appear to use that approach, but I'd humbly suggest that if CIDER was to take one approach, it could be that one or an equivalent one.

[mathvdh]

Hello everyone @here
I have a few comments to do :
First the integration with grimoire doesn't work anymore for me and I think the reason is that conj.io is DOWN (I'm not sure if it's temporary but it seems it's not)
Secondly I would be very interested to work on the feature of integrating with https://clojuredocs.org/ as the official clojure documentation is somewhat not very useful honestly.
So where should I start for such a integration ? I have not much experience with emacs or elisp but I have a lot of programming experience in general ... Any hints ?

[mathvdh]

Ok so I have been digging a bit more and it seems it's already implemented ;)
I found :
cider-clojuredocs
cider-clojuredocs-web

Maybe we should close this issue ?

[bbatsov]

Yeah, we should. I implemented the ClojureDocs integration a while ago, but I forgot to close this ticket.