Fork me on GitHub
#cljdoc
<
2018-07-23
>
martinklepsch10:07:23

@hiskennyness is this the repo/code used for the cljdoc builds? https://github.com/kennytilton/matrix

martinklepsch10:07:59

@hiskennyness please try again now, I think I fixed the root cause (a very old CLJS version being pulled in) — an issue I introduced with a recent refactoring… 🙂

kennytilton13:07:14

OK, will do. I had gotten pulled into other things. Yes,

<dependency>
  <groupId>com.tiltontec</groupId>
  <artifactId>matrix</artifactId>
  <version>0.1.4-SNAPSHOT</version>
</dependency>
has been my target.

martinklepsch14:07:49

I think this should work by now

martinklepsch14:07:59

but keep me posted to confirm 🙂

kennytilton14:07:00

Ok, once more into the breach!

kennytilton14:07:46

Should I run locally or against your site? I just got some ugly fails just starting the script after pulling the latest, before hitting lh:8000. Maybe a few stack traces can be ignored?

martinklepsch14:07:31

feel free to just run build on http://cljdoc.xyz

kennytilton14:07:27

First was

clojure.lang.ExceptionInfo: org.eclipse.jetty.io.EofException in Interceptor :io.pedestal.http.impl.servlet-interceptor/ring-response - 
	at clojure.core$ex_info.invokeStatic(core.clj:4739)
	at clojure.core$ex_info.invoke(core.clj:4739)

kennytilton14:07:45

Let me try again on a better wi-fi…

martinklepsch14:07:02

I already built it earlier. ⬆️

martinklepsch14:07:38

Not sure about that exception but sometimes Pedestal logs weird exceptions that don’t seem to affect functionality, have yet to figure out why

kennytilton14:07:13

OK, works locally, too, now. My Mac had jumped over to a slow wi-fi. OK, great, time for me to fill in some docstrings!

martinklepsch14:07:02

@hiskennyness sounds good — also consider following up on the tips given here regarding Git urls etc: https://cljdoc.xyz/builds/2335

kennytilton15:07:58

Ouch, thanks, I saw that and was going to check it out after reporting my sucess but forgot all about it. Looking at it now…

martinklepsch15:07:38

It’s not a big deal if you’re only after API docs but I suppose you’ll also want to integrate articles in some way

kennytilton15:07:25

Definitely. OK, so I am looking at this from sample.prj

:scm {:name "git"
        :tag "098afd745bcd"
        :url ""
        ;; Allows you to use a repository in a different directory than the
        ;; project's root, for instance, if you had multiple projects in a
        ;; single git repository.
        :dir ".."}

martinklepsch15:07:53

you really just need :git and :name if thats what you’re wondering

kennytilton15:07:01

…and I am lost. Why am I referencing a tag? Is that so my doc remains stable while I am hacking about? That would make sense. And what is with the url on localhost? Ah, I guess GitHub is not necessarily involved? But then how does your Web tool get to my system? Does the .git get deployed to Clojars? Also, I am toying now with having a multi-project repo so I like the directory option, but “..” is the one above me. Why not “.”? Hmmm, lemme pester #leiningen channel…

kennytilton15:07:08

Did you mean :scm {:name "git"}?

martinklepsch15:07:04

@hiskennyness :scm {:name "git" :git ""}

martinklepsch15:07:49

That’s really all you need, I’ll add an example because I agree that project.clj sample is a bit confusing due to it trying to exhibit all possible use cases

kennytilton15:07:50

I know. Documenters cannot win! I either complain because every example is trivial or because they provide complete examples covering every option but do not make clear when/why each option is needed. I will toss in the :scm and see what comes up.

dominicm15:07:27

Behavior driven documentation? Anticipate all the behaviors your users may be interested in, and then write documentation explaining that "flow".

dominicm15:07:39

The flaw is painfully obvious for some tools 😞

kennytilton15:07:31

Back when books were a thing, I liked the Black Book series that documented X as so many use cases of things a developer might want to do with X, pulling together in one solution the multiple elements of X that might be needed to solve a real-world problem.

kennytilton16:07:30

I have added the SCM info but when I attempt to regenerate it just takes me to the doc already built. This says I should not have to bump the version since I am at SNAPSHOT:

SNAPSHOT releases will use master as Git revision as they usually have no tag in your repo or sha in a .pom. This can be useful for experimenting with cljdoc.
Not so?

martinklepsch16:07:53

Have you pushed a new SNAPSHOT release with the updated .pom?

martinklepsch16:07:09

Will try to mention this somewhere

kennytilton17:07:51

“updated .pom”? I thought I was adding a :scm property to the toplevel of the defproject in project.clj. And when you say “new SNAPSHOT”, well, I have re-deployed to the same 0.1.4-SNAPSHOT version on clojars.

kennytilton17:07:43

I see Boot folks have to do something with some pom. I also see further down an unqualified

Now when cljdoc reads documentation from your Git repository it does not simply read it from master but instead tries to find a Git tag or a revision in your project's .pom. 
I see a pom.xml in my repo and have no idea what tooling put that there. 🙂 I looked at the cited git issue on versions and am starting to think the only way to experiment with :scm and :dir is to change the version on each try, but now I am concerned about the emphasis on a pom file so will await further word.

avi18:07:39

Hi, I just checked out the site and it’s really exciting!

avi18:07:36

One question: I tried searching for spec and spec itself, the canonical library, didn’t show up in the results — even after I entered clojure.spec.alpha — is there a specific reason it’s not included or not found, and is there a chance it might be added at some point?

martinklepsch18:07:25

@aviflax the search currently only queries Clojars and clojure spec is deployed to Maven Central I think

martinklepsch18:07:41

@aviflax you can follow the URL pattern described on the homepage to get to it 🙂

avi18:07:45

Hmm, OK. That’s good to know, and I can save a bookmark of course, but I was hoping spec, core.async, etc would just show up in the search. It’d also be cool if I could “favorite” docsets so instead of having to maintain bookmarks locally or whatever, I could just go to cljdocs and if I’m signed in I’d have quick access to those favorites… :thinking_face:

martinklepsch18:07:55

That would definitely be cool. Could even be a quick switcher that just maintains a list of libraries you visited in localstorage. Feel like opening an issue for this?

👍 4
martinklepsch18:07:14

FWIW it would also be neat to exclude the few popular Clojure libs on Maven central in the search results….

avi19:07:36

Yes! Exactly!

avi19:07:50

(for the first)

avi19:07:58

WRT that second… not sure I get it?

avi19:07:13

did you mean “include” ?

martinklepsch19:07:15

oh yeah, I meant include 😅

martinklepsch19:07:13

Right now that search string is sent to Clojars directly though so we’d need some hackery to include non Clojars artifacts. One option might be just including them via JS, another might be exposing our own search endpoint or using something like algolia.

martinklepsch19:07:40

There are some fans of algolia around here but I haven’t taken the time to really evaluate it.

avi19:07:23

:thinking_face: It might be simpler to search Clojars and Maven concurrently, asynchronously, and merge the results when/as they come back. However, having zero clues about how cljdoc works, I suspect such armchair architecture isn’t very helpful. Sorry!

martinklepsch19:07:12

> However, having zero clues about how cljdoc works, I suspect such armchair architecture isn’t very helpful. Sorry! No worries, the search is super basic, it’s literally 100 lines of JS. See search.js.

martinklepsch19:07:23

The issue with your suggestion is that there might be name conflicts or simply lots of java libs that are not relevant to cljdoc users.

avi19:07:21

OK, it makes sense to me that there might be some filtering required. So maybe that’s an extra step compared to the Clojars search. Still, architecturally, I’d think that the approach might work. 1. Kick off requests to Clojars and Maven simultaneously. 2. When Clojars results come back, display them as-is. 3. When Maven results come back, filter them, then display them. Whereby “display” I guess maybe I really mean “merge into the in-memory result set and then (re)render the results view” — I’m extremely rusty with UI work and it’s never been a strength of mine. My main point is, I think, if the search is already happening directly from the browser to Clojars, I’m not sure it’d really be necessary or desirable to move the search to a middle tier to add additional docs sources to the search.

avi19:07:26

Oh, and having an explicit merge step as part of the workflow might allow for explicit handling of conflicts… although maybe the handling could initially be as simple as “Clojars wins”

kennytilton18:07:49

We could not find the git repository for your project or link a commit to this release. API docs work regardless of this but consider setting these for optimal results.

martinklepsch18:07:12

@hiskennyness lets use a thread to sort this out

martinklepsch18:07:19

@hiskennyness that error message is misleading, need to fix it. Everything worked fine: https://cljdoc.xyz/d/com.tiltontec/matrix/0.1.5-SNAPSHOT/doc/readme

kennytilton18:07:59

Oh, great. So no errors at all, or is there still something to be improved on my end?

martinklepsch18:07:34

no errors at all, error is just misleading 🙈

kennytilton18:07:43

Next issue is hiding internal stuff — or is that a bad idea for a core library? Someone wanting to hack on Matrix will want to see everything! But some using Matrix on a web site wants to see only the API. Anyway, do things like defn- and ^private get excluded? I guess I could just move the API into matrix.core and matrix.macros and let folks figure it out.

kennytilton18:07:17

I did throw in one dummy defn- which was excluded, so guessing yes. But real defn-’s broke compilation left and right.

martinklepsch18:07:03

What do you mean with “real defn-s broke compilation”?

martinklepsch18:07:32

Private vars get excluded but you can also add ^:no-doc metadata which will exclude things as well

kennytilton18:07:55

Sorry, just spotted that part of the doc! 🤕

martinklepsch18:07:00

no worries 🙂

kennytilton18:07:20

(I bumped it to 0.1.5-SNAPSHOT just to see if it would like my :scm. Different message, anyway! I am sure my unorthodox file structure is at play. No one in #leiningen has offered anything yet.