README extension for Python projects

PyPI has no requirement that the file is called README or README.txt, so just call it README.rst. In fact, PyPI will not as far as I'm aware look in your package at all (although I could be wrong there, I haven't studied the code or anything), the text that ends up ion the front is the long_description parameter.

Then in your setup.py, you do something like this:

setup(name='Your module name',      version="1.0",      description="Whatever, dude.",      long_description=open('docs/README.rst', 'rt').read())

A crude way I can think of is to make a symlink to README called README.rst and check them both in.

You could use a git filter driver which would, on checkout, take your README.md (needed by GitHub) and generate a proper README (needed by Python, although Lennart Regebro's answer suggests that PyPI does not require any README file)

So, keeping aside the fact that PyPI doesn't need a README (and the warning could be simply ignored), here is how you could (in general) generate the expected file with Git:

However, any modification to that private file README would need to be reported manually to the README.md file (at least because of markdown syntax which no script can guess for you)

That is why Noufal Ibrahim's answer (which I upvoted) might be more adapted, especially if you have access to symlinks (I am still with Windows Xp at work, so no luck for me):

Having make README being a symlink to README.rst, or, as Arto Bendiken comments:
=> having README.rst being a symlink ro README.

Git will store the symlink (and not the file the symlink refers to), so you can have both README and its README.rst file in your Git repo.