Fork me on GitHub
#cljdoc
<
2023-01-05
>
mkvlr12:01:46

@lee thank you! Think the main issue Clerk is running into is not everything on Clerk’s classpath can be analysed successfully. Wondering if a best-effort analysis is something you ever considered?

mkvlr12:01:12

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

mkvlr12:01:37

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

lread12:01:49

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

mkvlr12:01:28

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

mkvlr12:01:46

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

mkvlr12:01:01

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?

mkvlr12:01:34

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

lread12:01:56

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.

mkvlr12:01:14

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

lread12:01:55

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

mkvlr12:01:42

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

lread12:01:46

Yeah, @U04V15CAJ 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.

mkvlr12:01:32

yeah, doesn’t sound too bad

borkdude12:01:14

@U5H74UNSF @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

lread12:01:42

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.

borkdude12:01:49

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

mkvlr12:01:08

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

lread12:01:06

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

borkdude12:01:36

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 ;)

lread12:01:07

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

lread12:01:49

I actually winced when you were summoned here.

mkvlr12:01:09

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…

mkvlr12:01:09

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

lread12:01:26

Yep, think so too.

borkdude12:01:20

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.

lread12:01:33

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.

borkdude12:01:54

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&amp;

lread12:01:36

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

lread12:01:35

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

lread12:01:52

But I loved crossclj

borkdude12:01:58

public API is good enough for starters

lread12:01:58

Something to think about...

lread20:01:10

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.

borkdude20:01:13

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)

lread20:01:09

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

lread20:01:33

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