Add a note about long_description_content_type='text/markdown'

[mrakitin]

It's possible to automatically render README.md markdown documents on PyPI. For that, an extra setup parameter is needed (example):

long_description_content_type='text/markdown',

I think it's worth to mention it in the documentation.

[danielballan]

The cookiecutter's README is an rst file. I judged it was easier to only discuss that one markup syntax, since rst is used in sphinx anyway. Do you think we should change it to Markdown?

[mrakitin]

No, I'm perfectly fine with the .rst format, the idea is to give users an notice in the documentation, that it's possible to also use .md files for rendering the docs on PyPI if they wish.

[awalter-bnl]

I think this starts to head us toward to many options. The beauty of this tutorial is that it keeps things very simple, I am not sure we want to confuse entry level people by giving them a bunch of 'options'. We could state from the start that in every step there are options but we have chosen to concentrate one one option in each case for simplicity.

[mrakitin]

@awalter-bnl, that's a fair point, though this kind of knowledge it usually struggled to obtain, so sharing may save people some time.

[awalter-bnl]

This is a fair point, I suppose the underlying question is who is this aimed at: Entry level scientists, where giving 'options' will confuse them, or mid-level scientists/programmers who want to find out what the options are.

Personally I think this works really well for entry level scientists as it is currently written, but I leave the question regarding who it should be aimed at up to others.

[danielballan]

I think this starts to head us toward to many options. The beauty of this tutorial is that it keeps things very simple, I am not sure we want to confuse entry level people by giving them a bunch of 'options'. We could state from the start that in every step there are options but we have chosen to concentrate one one option in each case for simplicity.

^ This is my thought too. I picture someone reading this and wondering, "So wait, do I have to know this? Why would I choose Markdown vs rst? Can I do my sphinx docs in Markdown too?" --- all natural questions that we would probably also have to address.

But I hear your point @mrakitin. The bummer is that this information is hard to discover, especially because this is a pretty new feature of setuptools. Maybe we could stuff notes like this into something like an FAQ? Let's leave this issue open and circle back in a couple months to see if there is a natural place to stick tid-bits like this, in some sort of appendix or something. I'm sure we don't want to include on "the main path".

[mrakitin]

More info here: https://packaging.python.org/guides/making-a-pypi-friendly-readme/.