Fork me on GitHub
#cljdoc
<
2022-01-25
>
Sam Ritchie00:01:08

woah cljdoc build was smoking fast!!

🚀 1
lread17:01:16

Heya @U017QJZ9M7W, did you get a chance to try https://github.com/cljdoc/cljdoc/issues/434 yet? If so, did it work for you?

Sam Ritchie00:01:11

nice work team 🙂

lread01:01:28

hmm… well… excellent! simple_smile

Jakub HolĂ˝ (HolyJak)08:01:22

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?

Jakub HolĂ˝ (HolyJak)12:01:08

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

lread13:01:21

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.

Jakub HolĂ˝ (HolyJak)13:01:16

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

lread13:01:40

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?

lread13:01:50

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

👍 1
lread13:01:49

(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!).

👍 1
Jakub HolĂ˝ (HolyJak)13:01:08

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)

Jakub HolĂ˝ (HolyJak)13:01:18

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

lread13:01:28

We could reference cljdoc-analyzer from cljdoc via tag and short sha, I think. Instead of via full sha.

lread13:01:55

Concrete is awesome!

lread14:01:41

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.

lread14:01:50

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.

lread14:01:32

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.

lread14:01:32

But maybe running cljdoc-analyzer as a tool is important/interesting to you for some other reason. Lemme know!

Jakub HolĂ˝ (HolyJak)14:01:16

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

lread15:01:45

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?

Jakub HolĂ˝ (HolyJak)15:01:37

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

lread15:01:33

Is that something you will be doing?

lread15:01:48

I only ask because every feature we add we have to support and maintain.

lread15:01:34

Which is fine if the feature is truly going to be used and benefit the community.

lread16:01:25

Watcha think?

Jakub HolĂ˝ (HolyJak)17:01:00

Yes, I would absolutely like to make that GH Action

lread17:01:15

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?

lread17:01:56

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

Jakub HolĂ˝ (HolyJak)17:01:45

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?

lread17:01:52

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

Jakub HolĂ˝ (HolyJak)08:01:37

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.

lread14:01:46

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

Jakub HolĂ˝ (HolyJak)15:01:18

I want thinking about that but it 💯 is sense

martinklepsch14:01:38

+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

lread14:01:05

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?

martinklepsch14:01:23

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

lread15:01:12

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.

martinklepsch15:01:15

Every way is welcome 😄

lread16:01:12

You are kind @U050TNB9F! simple_smile 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!