Markdown versus ReStructuredText

[jdkent]

I'm curious if @tsalo or anyone has thoughts about markdown versus restructured text for the documentation, in my project I bit the bullet and pretty much have everything using restructured text so it can be easily rendered by sphinx-text, but markdown is more common in the wild.

[tsalo]

I think using rst in the docs is best, and then we can use markdown in the repo proper (e.g., for the README, contributing guide, changelog). We can convert the markdown files from the top level of the repository to rst in the documentation with m2r.

[jdkent]

That sounds alright to me, for some reason I feel like there were no great tools for converting markdown to restructured text that I could find during Neurohackademy, but I cannot back up my claim with evidence.

[tsalo]

m2r has worked for me in the past, but I do remember it taking a while to figure out.