Clojurians Log v2
babashka-sci-dev
@t is currently investigating mkdocs for documentation for nbb. @pez and @ericdallo have good experience with this. It was recommended by @bozhidar to PEZ, but bozhidar is now using something else. Any reason for the switch?
I just like AsciiDoc a lot better for creating documentation. Also - Antora is very well thought out and brilliantly well supported tool. MkDocs gets the job done (I used it for a long time and I was reasonably happy with it), but doesn't hold a candle to Antora IMO. Probably it didn't also help that MkDocs on ReadTheDocs was constantly broken in one way or another. 😄
Yeah, with ReadTheDocs it was not fun using MkDocs. But since ditching RTD, MkDocs has served Calva very well. No idea what Antora is, but it probably is better. 😃
I evaluated Antora but according to polls, people by far favor a single page documentation site over a multipage thing with JS-based search. I've done the polls before and again last weekend and both times the results were unanimous...
A downside with that is that unfurls/social cards are document based. So all sections of the docs site get the same preview, same description, same meta. I don't want to make that trade off. And the MkDocs search is quite awesome.
I don't optimize docs for social media or mobile usage, but for developer-behind-the-laptop/pc usage
It has nothing to do with mobile usage. People, including developers-behind-the-laptop/pc, often share links to documentation with other developers-behind-the-laptop/pc over Slack, social media, etcetera. To me it is important that the preview gives reasonably good context, and I think ”Calva documentation” is too general, and prefer ”Calva Pretty Printing” or "Calva Getting Started”, etcetera, and not just about the title, but the description as well. Therefore I am not willing to make the tradeoff.
Like so: https://calva.io/api/
There are always trade-offs, and this preview context costs me in some ways. But to me it is important so I am paying those costs.
I don't see any preview ;)
I've done polls twice now and most people want a single page. I'm not the person reading the docs, but the person writing the docs, mostly, so I'll just go with what users prefer
> I don't see any preview 😉 Funny, but it looks like so for people who can see it. Similar on other platforms.
In my case I am often the person sharing links to the docs. 😃
@t has joined the channel
@pez has joined the channel
@ericdallo has joined the channel
@bozhidar has joined the channel
I used https://squidfunk.github.io/mkdocs-material/ for multiple projects: https://clojure-lsp.io/, https://emacs-lsp.github.io/lsp-mode/, https://emacs-lsp.github.io/lsp-dart/ and others, I really recommend using it
for lsp-mode, there is even custom elisp code that generates all functions and variables docs programatically and convert to markdown to be on the webpage
Ohhh, I must fix some of that generated content for Calva as well. It's a PITA with the API docs!
> custom elisp code that generates all functions and variables docs programatically sounds a bit like https://github.com/borkdude/quickdoc maybe?
For clojure projects sounds good @borkdude