Switch from rst to markdown in docs

[aboutaaron]

.rst is a pain to write/remember and Markdown is more supported anyway. Is there a way to have Read The Docs and PyPi recognize .md docs? If so, I say we drink the kool-aid and switch.

[palewire]

I also prefer Markdown, but as far as I can tell the mkdocs on Read The Docs doesn't support left-nav tabs, admonition ... notes:: and other features we're using. Show me we don't lose those and I'm on board.

[palewire]

Also, back in my day on my lawn the kids were happy to write ReST up and down the hill on the way to school year round.

[aboutaaron]

I don't care old man! Rae Sremmurd and Nicki Minaj use markdown so I do too (not really, but they probably would).

[aboutaaron]

FWIW, http://docs.readthedocs.org/en/latest/getting_started.html#in-markdown

[aboutaaron]

But I'll double check the features

[aboutaaron]

Wise Master, can you put me on to these features we're using in .rst?

[palewire]

The table on contents in the left nav that allows multiple pages. The ..note: boxes that make the funny warnings like here. Code formatting for snippets. Prefab templates for formatting class, method, function documentation.

[palewire]

The thing about Sphinx that is cool is that it is basically custom made for Python and has lots of sugar. Is there a way to get Sphinx to render Markdown?

[aboutaaron]

There was an effort add doctree parsing and other directives to markdown with a similar tool but that looks dead in the water.

It also looks like there's talk about it in the Sphinx repo but no movement yet for support. The doctree parsing and deep linking seem to be the hurdle.

Some folks are saying it's easier to extend rST and have it accept markdown syntax, but that's a hell I never want to enter. I'll just knuckle up and learn rST and hope some hacker decides to make this happen.

[mattbostock]

Note that this is now possible.

[palewire]

Matt, thanks for this update. I might not be groking it right away but will this new feature let Markdown support all the ..notes::, left nav and other extra stuff rST does?