Clojurians Log v2

with clerk I have cljs files like https://github.com/nextjournal/clerk/blob/main/src/nextjournal/clerk/render.cljs on the classpath, the deps aren’t part of the regular classpath but only in an alias

but tagging the class as :no-doc also felt wrong to me which is where I stopped

Ah that was what I was wondering. So that is part of your public API therefore :no-doc is not appropriate?

yeah, I ship them with the jar so folks can jump to definition and get docs for them

(though there’s still a lot of holes in the docs)

for debugging things locally running the cljdoc analyzer was good but felt a bit indirect to have to build a jar after every change, wondering if it could also be possible to make it work against a local dir maybe?

(sorry for this braindump, not trying to put this work onto you)

Cljdoc learns about an API by actually loading nses. This allows it to discover load time generated vars (potemkin import-vars type stuff). But not every project needs this. Static analysis via clj-kondo would be suitable for most projects, I think. I would love to get around to implementing that as an option for cljdoc.

that sounds like a great strategy I’ve also employed to great success: outsourcing the work to the one and only @borkdude 🙃

> for debugging things locally running the cljdoc analyzer was good but felt a bit indirect to have to build a jar after every change Yeah, can't disagree. Testing locally replicates production but is slow and awkwardish.

but seriously: would be a good fit for clerk for sure

Yeah, @borkdude suggested this AGES ago. I've actually done quite a bit of looking into it. I wanted to get to a point where the APIs I am discovering are the same for dynamic vs static (except for load time generated vars). And was almost there I think.

yeah, doesn’t sound too bad

@mkvlr @lee Since you have summoned me, here is a preview of what you can get out of clj-kondo analysis https://github.com/nextjournal/clerk/blob/api-md/API.md

I think I might have got distracted by some other project. I was looking into when a ClojureScript API should include a Clojure macro... I think... https://github.com/cljdoc/cljdoc/issues/543... Anyway would love to get back to this.

$ time bb quickdoc
bb quickdoc   0.07s  user 0.02s system 62% cpu 0.150 total

yeah seems to cover everything cljdoc needs? Except dynamically imported vars like @lee says but maybe that can be the opt-in case?

Yep, I was thinking static would be the new default and the current dynamic would be an optin.

tbh I don't see why we need a centralized service like cljdoc that needs devops, etc, if you can just dump an API.md in your repo ;)

Yeah I think you lost patience for cljdoc a long time ago!

I actually winced when you were summoned here.

agree that docs are most helpful in your editor, which is why I haven’t invested time into making cljdoc work, but it does come up at times so…

but yeah making the static analysis just work:tm: without needing to do anything special for cljdoc would ideal I think

Yep, think so too.

Not to disparage the work done on cljdoc, I appreciate it. A centralized database could be helpful in navigating the clojure ecosystem's dependencies etc.

I have spent quite a bit of time on cljdoc, so I must see its value. Right? simple_smile I do like it for discovery of libs, consistent display of docs, search-ability.

something that seq-find is doing with clj-kondo analysis could happen in cljdoc, much more like that could be done I think https://seqfind.com/repo-list-page?_rp_=WyJeICJd&

Yeah, like the discontinued... what was it called?... that site where you could browse the Clojure source ecosystem.

crossclj

Right!

That would be perhaps a pivot for cljdoc which is currently only concerned with public APIs.

But I loved crossclj

public API is good enough for starters

Something to think about...

The https://mobile.twitter.com/crossclojure which includes old screenshots. Gives a glimpse of its features. And apparently only cost $10/month in server costs.

I think having as much of those things as static assets instead of having to run a server helps in driving those costs down and lowering maintenance. 4clojure was also taken down but https://4clojure.oxal.org/ won't likely ever go down (or can be easily hosted elsewhere since it's just a bunch of files)

Hmmm... yeah. Worth thinking about that aspect too.

https://github.com/phronmophobic/dewey is another project that is exploring this space (analyzing all Clojure sources).