cljdoc

https://cljdoc.org/ & https://github.com/cljdoc/cljdoc
Shantanu Kumar 2020-09-30T09:46:04.011800Z

Hi, does cljdoc pick up (i.e. consider documentation) EDN files in the doc directory of projects?

Shantanu Kumar 2020-10-06T15:36:33.044800Z

FWIW I ended up linking to the EDN files from a markdown doc that is rendered by cljdoc, because Github renders EDN decently too.

martinklepsch 2020-09-30T09:55:55.012100Z

Not really. What would you like to see being done with EDN files?

Shantanu Kumar 2020-09-30T10:40:55.012300Z

@martinklepsch These are sample EDN files for annotated reference. I can create markdown files out of them, but that’s manual work.

martinklepsch 2020-09-30T10:43:08.012500Z

I see. So right now you’d need to wrap them in Markdown or Asciidoc. I’d be open to a contribution in the direction of allowing people to point to EDN files as articles though

dominicm 2020-09-30T11:28:20.012700Z

You might be able to include them from asciidoc.

lread 2020-09-30T12:53:32.015200Z

If I remember correctly, cljdoc does not support asciidoc includes... maybe due to some default safety settings... can have a look if there is real interest.

dominicm 2020-09-30T14:21:43.017200Z

Ah, there'd be a bit of investigation to look at the tools available for protecting from include:/etc/passwd

lread 2020-09-30T15:55:36.017400Z

Ah yeah… that makes sense.

dominicm 2020-09-30T16:35:51.017600Z

Might be fine given that we literally execute clojure code anyway

martinklepsch 2020-09-30T19:42:58.017800Z

We don’t do that for this part of the process, only for the actual source analysis. The ingestion of articles happens on the cljdoc server

dominicm 2020-09-30T19:58:21.018Z

Ah, in that case, need to be more careful :)

lread 2020-09-30T20:06:44.020Z

A question… cljdoc https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#wikilinks only work from docstrings. Is there a reason why we don’t support wikilinks from articles? (for AsciiDoctor we’d have to use a different syntax, but it is possible).

martinklepsch 2020-09-30T20:14:12.020200Z

Do you mean to link to namespaces/vars?

lread 2020-09-30T20:28:51.020800Z

Ya!

martinklepsch 2020-09-30T20:42:50.021Z

These links wouldn’t work on GitHub etc. and linking already is possible/practical with using CURRENT as version

martinklepsch 2020-09-30T20:43:31.021200Z

So I think my main argument against this would be that it creates a poor experience on other platforms with only a mild improvement in the authoring experience

lread 2020-09-30T20:49:52.021600Z

Fair enough. Tx!