A couple of beginner questions about cljdoc

#1

Why is it that when I type “integrant” in the search box, it is not the first item in the drop down list? I had to scroll down to find it in the ninth position. How are the list items sorted?

How do I request documentation for a version of a library that has not been loaded yet? I navigated to the Known Versions of Integrant page, but I couldn’t figure out from there. There is no “load documentation for a different version” button on that screen:

46%20AM

Appreciate any information.

#2

If you edit the version in the URL, then it will kick off an analysis.

Like you have: https://cljdoc.org/d/cli-matic/cli-matic/0.3.3/doc/readme and you change it to https://cljdoc.org/d/cli-matic/cli-matic/0.3.buggybeta27/doc/readme it will try and find it.

That’s how I rebuild docs for my projects. But I’m sure @martinklepsch has a better answer.

1 Like
#3

Hey Lance,

The search is currently backed by Clojars’ own search API which unfortunately is pretty poor :frowning:

https://clojars.org/search?q=integrant&format=json

There are a couple of issues around this on GitHub as well. I think eventually cljdoc will maintain it’s own Lucene index and swap that in wherever the Clojars specific API was used before. Maven repositories also provide some search facilities which is something I’ve been meaning to look into.

A short term solution could also be searching the results again client-side to ensure the ordering is reasonable. We already have some fuzzy search code in the frontend so it might even be relatively easy.

Why not improve Clojars search? Clojars is just one Maven repository and we’ll want to support search across multiple Maven repositories.

@l3nz’ suggestion here is pretty on point so far. Replace the version number in the URL with whatever you’re looking for. The listed versions are the ones for which documentation has already been built. Documentation is built automatically when artifacts are published to Clojars for the last 6 months or so but older versions may not have been built yet.

Very recently I’ve added a global index page with a small widget that can help users to find specific documentation as well. It might make sense to add a version of that to the page you included a screenshot of.

Let me know if this answers your questions and thanks for taking the time to ask them and give feedback :slight_smile:

#4

When you say this do you mean rebuilding as in rebuilding existing docs or building docs for stuff that hasn’t been built yet? There’s a hidden rebuild button left of the GitHub link in the top right if that is any useful. :slight_smile:

1 Like
#5

@martinklepsch,

A couple of follow up questions…

Regarding the search results:

For this specific example, I am seeing different results for https://clojars.org/search?q=integrant&format=json versus the cljdoc search. The search on Clojars gives me the desired result as the second element in the vector but the cljdoc search gives me the desired result as the ninth item in the dropdown list. I expected the results to be the same but the Clojars search appears to be giving better results. Can you double check and make sure I am not making an error?

Regarding displaying earlier versions:

I tried the solution you and @l3nz recommended but I am getting an exception. First, I confirmed that Integrant has a version 0.6.3 on Clojars, and then I tried the following two urls on cljdoc:

https://cljdoc.org/d/integrant/integrant/0.6.3/doc/readme
https://cljdoc.org/d/integrant/integrant/0.6.3

In both cases I got: An exception occured, sorry about that!

Is there something wrong with the urls I entered?

#6

Hey Lance! All very valid and helpful points!

Apparently at some point I thought it would be smart to sort by the created date that the JSON includes. I removed that bit so now items are rendered as they are returned by Clojars (see commit). Thanks for making me double-check :slight_smile:

I pushed some fairly big refactoring and improvements over the last days and there was a bug in the way it was determined if documentation for a project is available or not. Fixed, see commit.

I also pushed some small improvements to the quick switcher that you can bring up with cmd + k (or ctrl if you’re on Windows/Linux). Try it out if you haven’t already.

And make sure you clear your caches to get the latest and greatest JS.

1 Like
#7

Looks good, everything is fixed thanks :grinning:.

1 Like