This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2022-01-25
Channels
- # announcements (3)
- # asami (63)
- # babashka (5)
- # babashka-sci-dev (32)
- # beginners (56)
- # calva (2)
- # cider (28)
- # clj-commons (9)
- # clj-kondo (16)
- # cljdoc (41)
- # cljs-dev (19)
- # clojure (67)
- # clojure-europe (15)
- # clojure-nl (1)
- # clojure-poland (1)
- # clojure-uk (2)
- # clojurescript (27)
- # community-development (10)
- # data-science (2)
- # datascript (8)
- # datomic (21)
- # events (3)
- # fulcro (54)
- # graalvm (18)
- # introduce-yourself (2)
- # juxt (3)
- # lsp (6)
- # music (1)
- # nextjournal (8)
- # off-topic (44)
- # omni-trace (1)
- # reitit (13)
- # releases (3)
- # rewrite-clj (4)
- # shadow-cljs (10)
- # spacemacs (6)
- # sql (12)
- # tools-build (17)
- # tools-deps (3)
- # web-security (1)
Heya @U017QJZ9M7W, did you get a chance to try https://github.com/cljdoc/cljdoc/issues/434 yet? If so, did it work for you?
nice work team đ
Hi folks! Is there a way to run cljdoc on a library to verify that its docs do build, ideally as a GitHub action?
It would also be neat if the analyzer (which is the responsible artifact, I assume) was usable as clojure build tool so that you could clojure -Ttools install io.github.cljdoc/cljdoc-analyzer ...
and then invoke it via that (similar to https://github.com/seancorfield/deps-new).
Subquestion: Is it so that I need to at least publish a library to a local maven repo to be able to analyze it, i.e. it is not able to analyze a (deps-based) library from a github repo or a local directory?
Making the analyzer into a Clojure CLI tool: https://github.com/cljdoc/cljdoc-analyzer/pull/44 - with examples of using it to analyze a local / remote lib
Hiya @U0522TWDA! Cljdoc-analyzer does API analysis which is one part of the docs build. The other part is the articles. We do have a little shell script to help with verifying cljdoc.edn, but were thinking of rewriting that in Clojure/Babashka. Also... Another thing folks often get wrong is the pom scm info.
In the case of Fulcro it is the analysis that fails sometimes and thus that's what I want to be able to run eg on the CI to discovery such breakage sooner
Ah, I see, thanks for the concrete use case! That really helps. Just thinking out loud here... I suppose this would mean we'd need to start version tagging the cljdoc-analyzer git repo?
You'd want to be testing with the version of cljdoc-analyzer that is being used by cljdoc. So maybe the current RELEASE? (Which we don't have yet, we work with git shas currently).
(BTW, interesting idea @U0522TWDA! Just trying to wrap my head around what it means and pros, cons, etc as I sip at my first morning coffee!).
I'm not sure about details of Tools. Maybe it can work with old good hashes, without tags. "Current" would be optimal though all problems do had would be detected by any recent version (since my original fix)
To be very concrete : I want to run Cljdoc on CI to prevent Re-occurrence of issues like the one fixed here https://github.com/fulcrologic/fulcro/pull/503
We could reference cljdoc-analyzer from cljdoc via tag and short sha, I think. Instead of via full sha.
Oh wait. Yeah, you'd want to easily install current prod release of cldoc-analyzer. So ideally you don't want to be fiddling with short shas in your CI scripts.
So... just foggily exploring... I guess you don't absolutely need to run cljdoc-analyzer as a tool, yeah? You could just reference cljdoc-analyzer as a git dep under an alias with some main-opts. But you'd still have the issue of choosing the current production version of cljdoc-analyzer.
And rambling on... But if we started version tagging cljdoc-analyzer, the awesome antq would tell you when your cljdoc-analyzer dep is out of date.
But maybe running cljdoc-analyzer as a tool is important/interesting to you for some other reason. Lemme know!
I just thought that it is easier to run as tool. I can install it globally and run it on any project. Though adding it under an alias with :replace-deps (or what is called) and ombord with -X would also work. Nevertheless, the version issue is same for both
Was exploring the idea that maybe we don't absolutely need a PR for -X or tool support. Just maybe need to start git versioning cljdoc-analyzer?
An advantage of a tool is that it can be managed completely separately from a project's deps. So you could use it to make a reusable GH Action that checks that a project works with the analysis
Yes, I would absolutely like to make that GH Action
Ok, cool. So we just need to figure out the mechanics of ensuring the action is in sync with cldoc-analyzer production. Perhaps releasing cljdoc-analyzer would also create a new release of the github action?
I guess this action could also run our current cljdoc.edn verifier, would that make sense? https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#configuring-articles
If the analyzer is published to maven then perhaps we can simply :maven/version "RELEASE" (not sure whether /how this works) And yes, checking the edn would đŻ be desirable. How do you do it?
> If the analyzer is published to maven then perhaps we can simply :maven/version âRELEASEâ (not sure whether /how this works) Yeah⌠thereâs a bit of a weirdness about cljdoc-analyzer. It has that metagetta submodule. I did some testing around bundling this as a subjar wayâŚ. back⌠but it was a bit icky. > And yes, checking the edn would đŻÂ be desirable. How do you do it? See link above, it contains instructions. Check is a bit on the naive side currently, but better than nothing. Could be rewritten in Clojure to be OS portable and more extensive.
I have realized that perhaps if you simply tag the analyzer with latest
upon each release, it would be enough. (Git tags are mutable...) That would solve the versioning issue more less.
Regarding cljdoc.edn
- checking that would indeed be nice. But since its code is separate from the analyzer, it is unrelated to this PR. The GH Action could certainly do both, run the analyzer and run the validation bash script.
> I have realized that perhaps if you simply tag the analyzer with latest
upon each release, it would be enough. (Git tags are mutable...) That would solve the versioning issue more less.
Are you hoping to host the GitHub Action under the cljdoc GitHub org? If so, we could release it every time we release cljdoc-analyzer and maybe version it more conventionally? Just another thought.
> Regarding cljdoc.edn
- checking that would indeed be nice. But since its code is separate from the analyzer, it is unrelated to this PR. The GH Action could certainly do both, run the analyzer and run the validation bash script.
Yeah, just trying to help imagine the big picture and understand your use case. But good idea to break it down into smaller bits.
I want thinking about that but it đŻ is sense
+1 on all this, itâs been a longtime wish to help folks detect when their cljdoc build breaks (as part of CI)! Some people have the script to check cljdoc.edn in their CI steps but analysis is still unsolved
Would it make sense to start with a git issue? This is usually my personal pref for problems with more than one possible solution. Or is that too much ceremony? Does this thread do the job for folks?
The thing I have a high degree of confidence about: ⢠have a script that is easy to install/run in CI pipelines ⢠this script should operate on jars just like cljdoc itself Iâm generally ok with people just taking a stab at stuff, especially if itâs one of you two who have contributed quite a bit and are very familiar with it all
Yeah, I might tend to be more on the think than the do side of things. I don't want my style/pref to bog down a good idea from getting implemented.
Every way is welcome đ
You are kind @U050TNB9F! I can have strong opinions, I would hope that they are received as only opinions of one person. I donât want my opinions to thwart or deflate joyful cljdoc efforts!