Switch documentation from rst to md, improve examples and readability.

[entendu]

Is there a good reason to use a Python-y doc format for a PHP project on github? Markdown seems like the natural choice.

[xiongchiamiov]

To come back to this years later :), because Read The Docs was a good documentation-hosting site, it uses Sphinx, and Sphinx at the time only supported ReST.

Sphinx appears to have some level of markdown support these days, so that would be a thing to look into. Alternatively, mkdocs might be a sufficient replacement for RTD and could be published onto GitHub Pages. I don't know offhand what the api documentation story is for mkdocs.