Fork me on GitHub
#cljdoc
<
2018-07-18
>
martinklepsch14:07:40

Did a lot of documentation writing today, most importantly this guide for library authors. If any of you have 5-10 minutes โ€” Iโ€™d be thankful for any feedback ๐Ÿ™‚ https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.md

dominicm14:07:52

@martinklepsch use asciidoc, no more manual toc ๐Ÿ˜‰

dominicm14:07:54

it's the best

martinklepsch14:07:25

Haha, yeah, I should probably do that

dominicm14:07:06

I didn't look if contextually there was anything else (e.g. a html site)

kennytilton17:07:02

Good timing. I have huge library to document.

kennytilton17:07:35

Do you have a helloworld repo that illustrates all the features?

kennytilton17:07:43

What if I use the github wiki pages to do documentation? Will #cljdoc pick that up?

martinklepsch17:07:25

@hiskennyness cljdoc links releases to specific git commits and uses a checkout at that commit to build documentation. Since this kind of linking is not easily possible with wikis it does not support wikis.

martinklepsch17:07:52

We might be able to support this using submodules in some way but for now Iโ€™d encourage you to version your code and documentation alongside each other

martinklepsch17:07:09

@hiskennyness as for examples: - There is https://cljdoc.xyz/d/metosin/muuntaja/0.6.0-SNAPSHOT/doc/readme with a custom cljdoc.edn. - If you donโ€™t expect to need nested articles you can also just name your files in a sortable way, their first heading will be used as title in the sidebar: https://github.com/functionalfoundry/macros/tree/master/docs

kennytilton17:07:16

Yes, I saw the bit on sortable naming. Reminded me of the good old days of Basic line numbering where we left gaps so we could add subcontent. ๐Ÿ™‚

martinklepsch17:07:22

haha, yeah, I suppose you could do that ๐Ÿ˜„

martinklepsch17:07:42

@hiskennyness let me know if you run into any issues, have more questions/ideas etc ๐Ÿ™‚

kennytilton17:07:17

What about github wiki pages? Sorry of I am being dense.

kennytilton17:07:09

Ok, so I can just go with a bunch of .mdโ€™s in a docs directory and number them intelligently, or use the edn trick to organize them hierarchically.

martinklepsch17:07:38

Yes, or you can even use asciidoc ๐Ÿ™‚