On 05/24/2015 04:29 PM, Mike Innes wrote:
> Ease of reading and writing are definitely the most important factors (for
> humans more so than computers). Doc strings are often read in the source
> file or in a terminal, for example, so they need to be readable as-is, and
> writing them shouldn't be a burden.
I never felt a significant difference in readability of md compared to
rst. rst might be slightly harder to write due some extra specialized
syntax, but then again md tends to be slightly more verbose because of
that so there's never a clean winner.
But overall the resulting source text is very similar.
What I really appreciate with rst is that you can basically write a book
out of the box (inline math!) and there's exactly one spec, while md has
always a different subset of features which trips me every time.
> Actually though, Markdown is just the default – you can use anything you
> want for docs, including RST. Just create an rst"blah" string macro that
> builds an RST("blah") object, or similar, and you're halfway there. Of
> course, you'll miss out on tooling we build for Markdown (e.g. formatting
> in the repl, text searches etc.) unless you implement it yourself. But you
> could make an RSTDoc package that does all of that stuff, if you really
> want it.
It was mostly a curiosity.
But I keep thinking about that nicely formatted inline-math in ijulia
while browsing documentation ;)
