Docs Format
xuhang57 opened this issue · comments
Our documentations have both reStructuredText (rst) and markdown (md) formats. I think we should use one consistent format and I would vote for markdown.
Please feel free to close this issue if you think this is unnecessary.
I could spend some time on cleaning this if that's ok.
I would be happy to have everything in Markdown. And change the titles too, some of them are in all caps, like UPGRADING.rst. Do one file per PR though (or multiple if they are tiny).
I agree we should be consistent. A bit of background: Stuff started off as all markdown, but at somepoint someone suggested we should move to rst, because it's more standard in the Python world. Folks kindof agreed, but we never really fully committed; we just started writing a mix. For me, part of this is that I basically think in markdown at this point; even my emails/crap I type in IRC are mostly valid markdown. (and markdown was inspired by the ad-hoc notation people were already using in plain-text media). I can do rst if needed, but there is more mental friction. My vote is for markdown as well; it gets used on the bug tracker for GitHub, so it's one less thing folks have to know. Consistency with the rest of the Python ecosystem would be nice, but meh.
There are few places that prefer .rst other than that I think it is ok to move to mark down.
I also vote for mark down. the files that are required to be in .rst I suggest we keep a copy.
I don't think it's worth duplicating the docs, Is there anything besides the README tha has a concrete constraint like this?
Just leave the required ones in RST, and change everything else to MD
I'm okay with that.