Adoc support in docstrings instead markdown

[clyfe]

A lot of folks prefer adoc to markdown. It'd be nice to support it in docstrings rendering.
This way, one could use adoc throughout, instead docs in adoc and docstrings in markdown.
Rendering would default to markdown; a flag in deps.edn or jar manifest would switch it to adoc.

[lread]

Thanks @clyfe!

My personal opinion is that, even though I am an AsciiDoc guy for docs I write, I am not over-burdened by using CommonMark in docstrings. Just like I am not over-burdened by using CommonMark to write up this comment on GitHub! 🙂

For the markdown elements that I use in docstrings, CommonMark and AsciiDoc are similar enough that my brain doesn't get overly muddled.

Here are the off-the-top-of-my-head design considerations from a discussion on Slack:

If we do entertain AsciiDoc docstrings we would need to do some thinking:

• How will this work? (I think you are suggesting an option in cljdoc.edn?).
• The wikilink syntax is likely not compatible with AsciiDoc. So we’d have to decide what to do there.
• We also limit CommonMark in docstrings by not allowing embedded HTML, would we need to do something similar for AsciiDoc?
• And I guess we should check for performance differences between the AsciiDoc and CommonMark renderers in this scenario.
• I have been looking, on and off for the last long while, at how cljdoc renders CommonMark and AsciiDoc (AsciiDoc rendering is currently a bit weak). One the the areas of study is maybe rendering elements a bit differently in a docstring because the visual context is different than an article. I wonder what this would mean if we allow the full rich set of AsciiDoc elements in a docstring. CommonMark’s limited visual vocabulary is actually helpful here.
• If you want to continue this adoc docstring experiment, exploration of rendering can be done in cljdoc-exerciser.

My current biggest concern would be sensible rendering. That and introducing, perhaps unnecessary, complexity to cljdoc.

[clyfe]

Looking at RDoc used by Ruby folks, they support multiple markup formats, and have a :markup: directive that can switch.

[clyfe]

How will this work?

A flag somewhere, not sure where best.

The wikilink syntax is likely not compatible with AsciiDoc

I believe <<foo>> would work for wikilinks in adoc.

[martinklepsch]

I don't want to fragment what formatting people use in their docstrings as I think it is nice for all tools to be able to assume it is Markdown (and some editors do that already). I'll close this issue but feel free to use it to further make your point about why other formatting styles should be supported. I'm open to change my mind. 🙂