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.
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.
On 24 May 2015 at 14:54, Yuri D'Elia <[email protected]> wrote:
> Hi everyone,
>
> I'm just wondering, why markdown is being used for the built-in
> documentation as opposed to rst? I guess emergent convention?
>
> Since sphinx is used to build the manual, I would have preferred to have
> the same formatting at least as an option. I was able to successfully
> reuse inline rst documentation in python projects to build parts of the
> manual, saving myself to rewrite good chunks of text.
>
> But I admit I'm partial to rst because of that (I use it everywhere I can).
>
> Is md maybe slightly shorter or has some advantage I don't immediately
> see? Easier/faster to parse?
>
>
