Markdown support

[methane]

Recent days, many python project have README in Markdown format.

[msabramo]

See #3

[AraHaan]

I for one support this as it is a pain having to convert tables that can be in the readme to restructured text that can very easily break the tables. This would then brevent such breakage of them.

[JulienPalard]

Having just pushed:

I searched and found this issue. It does not look impossible to classify markdown vs restructurextext documents, having a module to tell them appart may be a good start that may be upgraded later (like getting the information from the setup instead of guessing?), what do you think? Should I try to do it?

[JulienPalard]

I tried if it was possible to tell appart md or rst with the content only, looks not that hard:

https://github.com/JulienPalard/mdorrst

It's slightly biaised towards rst, which is not bad for this usage.

It may be used as a temporary solution for setup.py files not explicitly giving the format, what do you think?

[ewdurbin]

@JulienPalard love the idea behind mdorrst, just as a headsup: for the time being if this is to be used as a dependency for readme_renderer, it will require python 2.7 support until pypa/pypi-legacy dies.

[AraHaan]

Another thing I want in the markdown support. The good old fashoned checkboxes like so: - [x] or - [ ] They can be so useful on checking when features of things are added (or partially added).

[JulienPalard]

@ewdurbin Support for Python 2.7 done in mdorrst 0.3.0:

python2.7(tmp) mdk@lighthaven$ python2.7 -m pip install mdorrst
Collecting mdorrst
  Downloading mdorrst-0.3.0-py2.py3-none-any.whl
Installing collected packages: mdorrst
Successfully installed mdorrst-0.3.0
(tmp) mdk@lighthaven$ python2.7
Python 2.7.13 (default, Jan 19 2017, 14:48:08) 
[GCC 6.3.0 20170118] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import mdorrst
>>> mdorrst.from_text("[hey](http://example.com)")
'md'
>>> mdorrst.from_text("`hey <http://example.com>`__")
'rst'
>>> 

[ewdurbin]

@JulienPalard awesome, thanks. i know it's a headache :)

[AraHaan]

nice, what about cases like these:

>>> mdorrst.from_text("### Some Heading")
>>> mdorrst.from_text("<!-- some html comment. -->")
>>> mdorrst.from_text("- [ ]")
>>> mdorrst.from_text("- [x]")

?

Good thing I know that markdown also supports html stuff as well unlike rst.

[JulienPalard]

@AraHaan:

>>> mdorrst.from_text("### Some Heading")
'md'

Looks right: it will be rendered properly in makdown.

>>> mdorrst.from_text("<!-- some html comment. -->")
'txt'

As there is no clear indication that it's in fact markdown, fallback to text looks legitimate. It can be markdown as HTML is allowed, but it can be HTML, we can't tell the writer intention from this. It's really easy to hit "md" on this by adding 'html': content.count('-->') / 1000 on the markdown marker counters without breaking any tests, is it worth the modification?

>>> mdorrst.from_text("- [ ]")
'txt'
>>> mdorrst.from_text("- [x]")
'txt'

Those kind of checks list looks natively supported in markdown and are legitimate to use in reStructuredText, so no really clear indication here. Without clear indication the fallback is text. Again it's really easy to modify by adding a 'checklist': content.count('- [ ]') / 1000 markdown side without breaking any tests, should we?

But please note that READMEs are typically longer than that, so the detection is better (see the successfull detection of like 2k real life READMEs in the tests/ directory). (And that I personally don't really care if we fail rendering properly 5 chars long READMEs).

Also please note that this solution can be considered a fallback of a more robust one (like asking for the filename or type in the setup() function?). As, even if we start asking for the clear indication now, we'll still won't have it for past versions, and we won't get it on 100% of the new versions (from contributors following old docs, old tutorials, old cookiecutters, old habbits, those who don't care, those who don't know, etc...).

Finally, it can probably be enhanced, just it's actually better than nothing.

[AraHaan]

I agree.

[JulienPalard]

Continued the work of @msabramo, integrating mdorrst, on this PR: #51