[PATCH 0/6] Documentation, reStructuredText and readthedocs.org

[Finucane, Stephen]

> On Wed, Sep 30, 2015 at 07:01:37PM +0100, Finucane, Stephen wrote:
> > Could you kindly elaborate a little further on why you though it
> > necessary to transition to reStructuredText? We're not making use of
> > any of the fancy features of rest but it's still adds a lot of cruft
> > (a Makefile? In a Python project? Surely not! :D).
> 
> I wish you wouldn't use any kind of dogma to judge work. Why would one
> not use make and makefiles when it's handy to do so?
[...] 
> Overall, I don't think markdown offers enough documentation authoring
> tools for project-wide documentation. There are other alternatives that
> would work as well (asciidoc comes to mind), but given that it's a
> python project, I went for sphinx and reStructuredText.

No no, we're not trying to compare Markdown vs. rST here: as you've correctly pointed out they are different tools with different use cases. My question, which I don't think has been answered yet, is why do you think it necessary to transition to reStructuredText for this particular project? Are you planning to flesh out the documentation in such a way that we need features like TOC or images and figures? Do we plan on generating PDFs or other documents? Do we plan to include native markdown in our documents? If so, that's fantastic - just tell us as much. If not, you'd have to question the value of doing stuff for just because we can. I'm not in any way saying this is a bad idea so don't take it personally: I just want to understand your position on the matter so I can help you.

Keep up the good work!
Stephen

PS: If possible, could you include information like this (a.k.a. your rationale) in cover letters to help explain why you're adding a given features (cover letters, like commit messages, should focus on "the why" rather than "the what"). Reviewers don't necessarily have the "big picture" understanding of an issue that you might possess so it's super helpful!

PPS: I think you'd like this article on Markdown and some of the issues with it. Typical Ars excellence: 

  http://arstechnica.com/information-technology/2014/10/markdown-throwdown-what-happens-when-foss-software-gets-corporate-backing/1/. 

> --
> Damien