[Biopython-dev] Using markup for the README file on GitHub

[Peter Cock]

Hi all,

Matt Fenwick has suggested using some markup in the README
file in order to make it look nicer on GitHub,
https://github.com/biopython/biopython/pull/45

The major downside is for any markup to be rendered on GitHub,
you must use one of the supported extensions - which is a problem
for projects using README (no extension) or README.txt (which
is nicer for Windows users). As per a heated discussion on GitHub
https://github.com/github/markup/issues/3 it appears the hack
solution for projects wanting to maintain their existing convention
is to add a symlink with the markup extension (e.g. README.md
if using the markdown flavour), which is what I have tried on this
branch: https://github.com/peterjc/biopython/tree/markup

I didn't include all of Matt's changes since I wanted to balance the
rendered display and maximizing the plain text human readability.

While this does add a 'strange' file to the root folder, I think this is
probably a reasonable compromise.

What do you all think?

Personally I would prefer using reStructuredText in place of
markdown - because we are already using that in many of our
docstrings and it is supported by both epydoc and Sphinx.

Peter