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

[Finucane, Stephen]

> I've set up a patchwork readthedocs account and added the necessary
> scafolding
> to get documentation generated from docs/
> 
>   http://patchwork.readthedocs.org/en/20150929-readthedocs/index.html
> 
> While we had the documention in markdown, I found that reStructureText is a
> full featured documentation system while markdown is good for smaller
> snippets.

Nice work. It's good to get this on readthedocs and it will allows us to fill out the documentation over time (I found the lack of documentation to be the single biggest barriers to getting started with patchwork).

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). There's also the fact that reST looks awful on GitHub and is a good deal more difficult to write than Markdown. As for integration with the Python ecosystem, while this is certainly true is some cases (OpenStack are currently undergoing a transition from XML-based DocBook, for example, but they're dealing with a *crazy* amount of documentation) it's worth noting that tools like Markdown are very much a first class citizen on ReadTheDocs and in Python these days. Overall, I think it's a lot of pain for practically zero gain. Thoughts?

> reStructureText intregrates quite a bit better with the rest of the python
> ecosystem as well. I took the liberty to convert what we had in
> reStructureText
> then.
> 
> I've written a few patches/fixes on top, no deep changes though.
> 
> HTH,
> 
> --
> Damien