Support Markdown format: README.md etc.

[nealmcb]

When cookiecutter-pylibrary was written, PyPI didn't support Markdown, but now it does. Sphinx also supports Markdown pretty well now.

So would it make sense to add an option (and templates? and ??) so that pylibrary could generate a Markdown-based project?

What other functionality would be needed in pylibrary?

What other things would projects lose easy access to by trying to exclusively use Markdown? E.g. can sphinx.ext.doctest be used in Markdown docs?

[ionelmc]

Doesn't make sense unless there's a complete switch to markdown (mkdocs or whatever instead of sphinx). For example the readme.rst is included in the docs as an overview page. I am not familiar with mkdocs but if you have patience to fiddle with the jinja templates (expect spacing problems) i'll accept it :)

[nealmcb]

I see there's more to cleanly offering Markdown as an option. But I guess it isn't too hard for us Markdown fans to mix-and-match your reST docs with new Markdown docs via Sphinx.

And thanks for pointing me to MkDocs, which was not on my radar. They don't address docstring-based API documentation out-of-the-box, but there are plugins that can:

• API documentation building - MkDocs Plugins · mkdocs/mkdocs Wiki.

[ionelmc]

The point I was trying to make is that there is little value of only offering the readme in md format. You could still make a pr with just that I guess, if a readme.md is all you care about.

[ionelmc]

If there isn't an option to switch all the docs to a md system it's pointless to have just the readme in md.

If someone makes a pr with something like that (complete md docs option) I won't refuse it but it has to be good, and I won't be a fan of it.