Fork me on GitHub
Slack Archive

This page is not created by, affiliated with, or supported by Slack Technologies, Inc.

2019-04-22

Channels

#cljdoc
<
2019-04-22
>
seancorfield00:04:49

I also didn't realize that the friendly name used in cljdoc.edn also determines the actual URL, so I have a bunch of links that go to blank pages because I was trying to link to the filename instead 😞 I hadn't noticed because some of my filenames do match the friendly name.

seancorfield00:04:44

I'm getting there, slowly. I know there will be at least one more round of code changes before I actually announce this thing so I hope I'll have the documentation right by then 🙂

seancorfield00:04:31

Alpha 7 pushed and all the links are now correct! Yay!

martinklepsch01:04:15

Thanks! Please do open an issue if you have some (semi) specific suggestions to make the docs clearer. Doesn’t have to be polished, more about making a note before we all forget about it again :D

seancorfield03:04:44

I think the main disconnect -- for me -- was that on GitHub, I'd link to /doc/some-thing.md and I somehow expected that to be magically converted to whatever link cljdoc created for the same file, based on cljdoc.edn... which, after just a little thought, is wildly unrealistic.

martinklepsch04:04:10

@seancorfield but... thats how it works? 😄 I think I'm misunderstanding something

martinklepsch04:04:47

if you link to any md/adoc file that is also part of your cljdoc.edn those links will automatically be rewritten so that they point to their respective cljdoc counterparts

martinklepsch04:04:58

From what I understood the confusion stemmed from having a different expectation how the URLs are defined (i.e. based on title vs filename) but would be interested to understand if there was something else too

seancorfield05:04:36

Yeah, I think that's it. I assumed that the cljdoc.edn file would provide a two-way mapping so links to actual doc/whatever.md files would be mapped to the URL associated with the "What Ever" name -- what-ever -- but that didn't seem to happen. Should it @martinklepsch?

martinklepsch13:04:00

@seancorfield can you point me to some specific link that you expected to be rewritten? From what I understand this should work but there might be a misunderstanding so it might help to talk about something specific

seancorfield19:04:13

Hard to say. I took the comment in the docs pretty literally: that rewriting means a link that works on GitHub also works on cljdoc.

seancorfield19:04:03

So I expected that relative links within the doc/*.md files -- to each other -- would be rewritten to link to the same place in the generated docs on cljdoc itself.

seancorfield19:04:05

If I had doc/getting-started.md and it linked to just rs-builders.md -- which works on GitHub -- then in the generated docs it would link to /doc/getting-started/result-set-builders per the mapping in cljdoc.edn.

martinklepsch03:04:06

I dug a bit more into this and found a bug that's now fixed in production. Tested it with these changes to the next.jdbc repo: https://github.com/seancorfield/next-jdbc/compare/master...martinklepsch:cljdoc-fixes?expand=1

martinklepsch03:04:18

they're not complete but hopefully helpful enough

martinklepsch03:04:53

In general that "if a link works on github it should work on cljdoc" thing is true and if it isn't, that's a bug 🙂

seancorfield03:04:11

Nice! Thank you for such a swift fix!

seancorfield03:04:49

I've done a full regex find'n'replace to fix them all for the next release (rather than take the partial PR). I have more documentation to write (the whole datafy/`nav`/`:schema` thing needs its own page). And, of course, I can only update all the docs when I make a new release 🙂 Alpha 9 contained one tiny bug fix -- and a lot of documentation updates. Alpha 10 will probably be similar, depending on when (if? 🙂 ) I find the next bug!

martinklepsch04:04:36

and (unrelatedly) that you can use [[with-transaction]] to link to other vars in docstrings like this one: https://cljdoc.org/d/seancorfield/next.jdbc/1.0.0-alpha7/api/next.jdbc#transact

martinklepsch04:04:03

(for other namespaces the sym needs to be fully qualified)

seancorfield04:04:59

Yeah, I haven't started using WikiLinks in docstrings yet. That's on my list, now that I have cljdoc mostly under my belt 🙂

seancorfield04:04:20

And good to know re: local building... I will check that out tomorrow!

seancorfield17:04:46

Being able to run cljdoc locally and importing a project -- wonderful! Thanks for pointing me at that!

martinklepsch17:04:15

have you been using branch names as revisions? I had some weird issue with that yesterday so curious if you tried that and if it worked for you

Nick20:04:26

It looks like (all?) attempts to build cljdoc for yetibot https://cljdoc.org/builds/12702 fail during API import due to Too long with no output (exceeded 10m0s).

martinklepsch00:04:17

Hey @UETBU4DT6— I've sent @U066S8QGH a message about this: [...] for Yetibot I think the issue might be that some thread pools are started in the background. There seems to be some dirigiste / manifold stuff — if you want to look into it I'd suggest you look out for that kind of stuff To test stuff you can clone this repo: https://github.com/cljdoc/codox/tree/cljs-proper/codox make sure you check out the cljs-proper branch and then run clj -Sdeps '{:deps {yetibot {:mvn/version "0.5.18"}}}' -m codox.main clojure yetibot-0.5.18.jar with a version that you've installed into your local maven

martinklepsch00:04:56

Happy to help with this but wanted to wait of Trevor has some ideas where those threads might be coming from