Clojurians Log v2

Particularly interested in attaching extra narrative (markdown) and examples. I found https://github.com/cljdoc/cljdoc/blob/master/doc/roadmap.adoc#examples is on the roadmap, perhaps something we can talk about?

What would you like to add? The docstring can contain markdown.

one situation is including a chart or detailed example that shouldn't be in the docstring (because that is for REPL consumption). Basically just augmenting the docstring with a bit more information, ideally one that can show an image.

One answer is that everything should go in the docstring, and maybe it's more a question then can images be included in a docstring.

I've never tried it, but maybe it works.

Do you want to have it in the documentation of the code? You could cross-reference code and an external markdown file, for example.

Right. One concrete case is the "Tableplot" library which currently is not on cljdoc. The docstrings are insufficient. Rather the api is documented in this way: https://scicloj.github.io/tableplot/tableplot_book.plotly_reference.html#layer-bar where an example is shown. Cross-referencing is in general a good idea but doesn't quite solve the need to have a bit more than just the docstring.

Ideally we should bring Tableplot to cljdocs regardless of if it can include examples or not, but also if there is an opportunity to add something simple to cljdoc to achieve it, that would be fantastic.

BTW, Claude Sonnet 4 is pretty good in in writing meaningful docstrings with examples.

In the case of Tableplot, one thought is simply if there was a way to provide a mapping of vars to images, that would be enough to show the visualizations that result from the examples.

For the images, you could create a markdown file with referenceable headings per example and reference them from the docstring, if including image links doesn't work.

For reference apparently in codox, it was somehow possible to interleave examples with the docstrings. https://generateme.github.io/fastmath/fastmath.signal.html#var-effect though in the case of Fastmath 2 at this link above, generateme did something special to generate those systematically. https://github.com/generateme/fastmath/blob/master/metadoc/fastmath/signal_examples.clj#L35 I haven't read into the details yet.

Maybe the first goal should be to include ![example](example.svg) in the docstring as markdown, and supply an image file that will be present in the final built artifact/site.

Probably that already just works if I put example.svg in /docs 🤔

Markdown is supported in docstrings, and you can reference images. For an idea of what is available take a peek my little playground: https://cljdoc.org/d/org.cljdoc/cljdoc-exerciser/1.0.123/api/cljdoc-exerciser.core

awesome, that's very helpful thanks