Clojurians Log v2

On some projects I've created a bb cljdoc-preview, it doesn't make the process less heavy, you still have to push your changes, start a cljdoc docker server and then ingest your docs, and then view them. But it abstracts the nitty gritties. Here's the https://github.com/clj-commons/etaoin/blob/07277c1f78ec9bed74b9c7b74084897346adc2c3/script/cljdoc_preview.clj#L1-L253 that backs the task for etaoin.

@lee why do we need to use docker at all and can't we invoke a pure Java lib?

I think it would be awesome if you could generate the docs locally more easily for previewing and detecting errors early. Optionally: upload them in a cljdoc folder or branch and self-host them. And cljdoc could pick up on those as "pre-generated" such that it doesn't need the analyzer remotely again

Yeah, I think we even chatted about something similar a while back @borkdude: https://github.com/cljdoc/cljdoc/issues/565.

I also think an option for static analysis will solve a ton of problems for folks. https://github.com/cljdoc/cljdoc/issues/543

The first source of truth for cljdoc is currently the jar. And that is also currently the case for preview. The advantage is that this mimics production, the disadvantage is that it is awkward and heavy.

@lee Maybe integrating with tools/deps and being able to provide a SHA could work too?

E.g. nextjournal/garden does nice job of this: you can build it locally and on the server, using the same config in our deps.edn: https://github.clerk.garden/

the sha is part of the URL: https://github.clerk.garden/nextjournal/clerk-demo/commit/abc5922720cf1ddfbfc4dc3499f83ca94e08685d/

this would solve the preview problem for me too, first I would request a specific sha, make changes and then release to clojars

Yeah, if you mean building docs from hosted git sources, we have an open issue for that one too: https://github.com/cljdoc/cljdoc/issues/459 Sean and I hashed out many details for that one.

I'll take a peek at the clerk strategy to see what we can potentially steal (find inspiration from).

one aspect of clerk is "local first", which I think is one of the frictions it solves compared to existing "notebook" solutions

Yeah, cljdoc was certainly not designed with local-first in mind.

But that doesn't mean it has to stay that way.

Until the cljdoc preview flow improves @borkdude, I'll volunteer to review/preview for your projects. Just lemme know which ones you'd like me to monitor. Not ideal, because it would be better for you to preview quickly before a release, but maybe an ok compromise for now.

And the pain of doing this, might just motivate me to change cljdoc. simple_smile

Haha, deal! :)

And if you want my help with static analysis for cljdoc via clj-kondo, I'll gladly return the favor

Thanks! I actually got pretty far with static analysis. I got a bit stuck on a difference between static vs dynamic analysis wrt to macros and ClojureScript. The friction was enough to let another distraction distract me. But iirc, dynamic cljs analysis only includes macros if they are used/loaded by the lib and my static cljs analysis always includes all macros. We chatted about this at the time and you helped me to see that static analysis makes more sense because all macros can be potentially used from cljs.

@borkdude I've done a cljdoc sweep for sci and clj-kondo. Ping me whenever you need a cljdoc review/sweep help for any of your projects.

@hlship What I do personally is create an API.md using quickdoc: https://github.com/borkdude/quickdoc/blob/main/API.md This works well for projects whose vars can be detected statically. There is also codox, which works well. For publishing docs you can use Github Pages. cljdoc should work automatically

I generally prefer codox, and regenerate it which releases, then copy the codox to the appropriate docs subfolder, commit, and push.

@hlship yeah, cool. I recently discovered another way of doing this, without committing the generated html stuff to your local tree: You can build the codox (or ClojureScript, or whatever you want to push to Github Pages) on github actions This is the github actions config: https://github.com/borkdude/clj2el/blob/49f602a2a5f441946f48fd0d0c3b53109eeba2e5/.github/workflows/pages.yml#L42-L53

What I really like about http://cljdoc.org is that it a) includes all the API docs derived from the ns and var docstrings and it includes readme, changelog, and everything in the docs folder (and you can tell it how to structure that via an EDN file).

Yes, and leaning on that is simpler than the process I currently use!

Then you don't have to worry about any external doc-gen tools -- and you get automatic docs for every version of your project published to clojars!

(and you get the benefit of discoverability for your library when people search for stuff on http://cljdoc.org itself!)

One thing I find difficult about cljdoc though is that it's hard/slow to preview what is going to get generated. E.g. forgetting to add something to cljdoc.edn, a namespace which should not have been included in the API docs, etc

You can run it locally -- but I agree that's a bit clunky.

I contributed that "run it locally" initially

You can at least include a step in your GH Actions to verify the cljdoc.edn file 🙂

but after too many times that "analysis failed", etc, I gave up on checking how my docs looked on http://cljdoc.org (I should probably start doing that again)

I'm one of the maintainers for cljdoc. I like it and use it for clj-commons projects where I'm a maintainer. Agreed that local preview is awkward. But I have the luxury of not being pressed for time so it does not bother me too much.