convert README and Doc files to markdown?

PyPI recently added support for package long_description set in Markdown format, and Sphinx also supports Markdown (see http://www.sphinx-doc.org/en/master/usage/markdown.html). ReStructuredText may be more powerful, but life is too short to learn another markup language, and most people are already familiar with Markdown. I also believe that having the docs set in Markdown instead of RST may lower the entry barrier and we could get more contributions.

[gferreira]

not sure I qualify as a “Sphinx expert”… but here’s my 2¢:

• all Sphinx projects I’ve worked on were written in reST. I have yet to see a project using Sphinx with Markdown.

• it’s very easy to learn reST (and Sphinx) by looking at the source code of vanilla, defcon, fontParts, drawBot etc.

• the biggest barrier to writing documentation is writing documentation 😃

[chrissimpkins]

also generated documentation from docstrings for methods etc.

This is automated with RTD and is simple to implement. The sphinx-quickstart configuration tool does most of the work for you and RTD updates with every commit pushed to the repository so there is no documentation maintenance involved. Any undocumented areas would just need to have the docstrings updated.

manually written docs the README is something else… I agree it should be written in markdown

Agree. Would add that it would be helpful to have separate Markdown documentation (or a dedicated documentation website) for the executables in the project along with some common usage examples. Searching through RTD to find the module that implements the executables is an unnecessary barrier to understand how they work. I would recommend working under the assumption that many users with an interest in this project will approach it with no knowledge of the organization of the source and where to find this information in the automated documentation or source docstrings.

Hm, I guess I’ll have to learn reStructuredText anyway…

pandoc makes MD --> rST simple. It may support the rST --> MD direction as well. I am not a fan of rST and use MD --> rST whenever it is necessary.