README extension for Python projects

Question

Python packaging tools expect that our readme file should be named README or README.txt. But if we follow this convention, GitHub displays it as plain text in the project page which is not pretty. (unlike the beautiful HTML version when named as README.rst)

Is there any technique to make both PyPI and GitHub happy about README.

Answer 1

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()
)

Answer 2

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

Answer 3

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.

Answer 4

Quoting Éric Araujo at the Python bug about the distutils warning:

In packaging/distutils2, the recommended idiom looks like this (in setup.cfg):

[metadata]
description-file = README.whatever

sdist will include that file. You can also write the description in the setup.cfg directly and have your README file included with the extra_files field.

So, basically, ignore the warning from distutils about a missing README.txt. Also, distutils2 supposedly does not emit this warning (I haven't tested), so you could try upgrading.

Answer 5

In older (non-distutils2) setups, you can add your README.rst to the MANIFEST.in file explicitly. You'll still see a warning about the standard README{.txt} being absent, but your README.rst will be included in your sdist tarball, meaning it will be included for end-users who download directly from PIPY.

See http://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template for more details.