Fork me on GitHub
#cljdoc
<
2018-10-04
>
cfleming09:10:27

@martinklepsch I finally got to watch your cljdoc talk, very nice!

cfleming09:10:30

Have you thought about cross-linking libraries like crossclj did?

cfleming09:10:03

(sorry, I should have watched your talk live rather than blabbing in the hallway, then I could have asked intelligent questions in person 🙂 )

martinklepsch09:10:03

There was no time for questions so you did everything right 😄

cfleming09:10:07

Also, you should apply to clojurists together if you haven’t already.

cfleming09:10:45

Clearly I’m just not paying attention.

martinklepsch09:10:19

> Have you thought about cross-linking libraries like crossclj did? I have and it's certainly a cool thing to have but for now I wanted to focus on something that helps with "How do I use this library?" and a code-explorer felt a bit too tangential to this for now

cfleming09:10:57

Yeah, I can see that. I think there’s a bunch of useful stuff you could do there long term though.

martinklepsch09:10:53

I can see that it would enable a bunch of interesting things, yeah... do you have anything particular in mind?

cfleming09:10:30

Minimising dependencies, for one thing - if I only use this one function from this lib, do I need all its deps?

cfleming09:10:01

Which is along the lines of what Rich and Alex seem to be working towards, so perhaps wait and see what they come up with.

cfleming09:10:39

Another thing which has been useful for me is “show me usage examples of this fn/macro”

cfleming09:10:47

i.e. show me how people actually use this.

cfleming09:10:13

That relies on you indexing lots of stuff though, so that you have a lot of usages to find.

cfleming09:10:56

Are you using Codox’s markdown variant?

martinklepsch10:10:56

I'm using Markdown + codox style wikilinks

cfleming10:10:29

Nice, I’m planning to support that in Cursive too. That sounds like a standard to me!

cfleming10:10:54

Have you had problems with any docstrings rendering strangely if they’re not written with MD in mind?

cfleming10:10:22

i.e. do you try to detect at all if a ns is actually using it?

martinklepsch10:10:52

> Minimising dependencies, for one thing - if I only use this one function from this lib, do I need all its deps? While useful my gut feeling is that this problem is only relevant to fairly few and advanced devs so overall impact might be low

martinklepsch10:10:24

Not trying to reject good ideas here but I have to pick my battles and so far I've tried to be guided by maximising impact and focusing on people at the lower end of the learning curve

martinklepsch10:10:13

> i.e. do you try to detect at all if a ns is actually using it? No, intentionally rendering everything as markdown so people just start using it

cfleming10:10:23

Yeah, absolutely, that makes sense.

cfleming10:10:45

I think the show usages is more generally useful.

cfleming10:10:01

It’s trickier to implement though.

martinklepsch10:10:06

agree. Maybe I'll add a link to crossclj for that

martinklepsch10:10:31

there are situations where people have a code block that's indented 2 spaces, which subsequently looks broken

cfleming10:10:59

I can imagine core having a few problems there.

cfleming10:10:41

Anyway, it all looks awesome. I love the clj/s rendering too, I’ve been meaning to do that for ages in Cursive.

martinklepsch10:10:57

There recently was a button introduced to render docstrings as raw monospaced text, that's supposed to mitigate this problem somewhat while sticking to the principle of assuming markdown

tavistock11:10:41

how do you do static analysis in cursive, for macros and stuff? I seem to remember you mentioning it in a talk but can’t find anything else

cfleming11:10:45

@tavistock I’ve pretty much only described it in talks, and in discussions on issues etc. Basically I define grammars for macro forms, and then extensions to handle the parsed forms in various ways. The grammars describe how to capture various elements and then the extensions interpret the captured data.

cfleming11:10:36

I’m planning to open source all that so that users and library authors can add support for libs they write or use to Cursive, but unfortunately due to some bad early decisions that’s proving difficult.

tavistock11:10:07

nice, thanks

dominicm18:10:04

<<adoc-xref>>

😉 4
martinklepsch18:10:02

@dominicm what are you talking about? 😄

dominicm18:10:02

I really want to standardize those in Clojure docstrings. For entirely selfish reasons. It's a shame there's no real standards on this.

martinklepsch18:10:27

I don't even know what this is 😄

dominicm18:10:50

Asciidoc version of [[]]

Jorin18:10:07

Hi, a noob question: in the readme is a more REPL-driven workflow mentioned. So far I only tried lein or boot to do that. How could I start a repl in the cljdoc.server.system namespace using clj? Thank you 🙂

martinklepsch19:10:53

You run clj and move into that namespace (after requiring it) using in-ns. Then you can evaluate the forms in the comment block at the end

martinklepsch19:10:22

Offline for a bit now but maybe other folks in here can help further if needed :)

Jorin19:10:20

Thanks so much. The step I was missing was requiring the namespace before moving into it. Almost 😄 Working great now! If you don't mind I would send a small PR to mention this in the readme.

martinklepsch21:10:36

I’ve actually noticed today that the „running cljdoc locally“ file should also describe the repl workflow. If you feel like it you Code also add this there alongside the basic note from the reader

Jorin21:10:54

ah didn't see that file yet. Yes, will add 🙂