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

[Brad Chapman]

Hi all;
Matt -- awesome, thanks for looking at this. I'm agreed the GitHub
presence needs a bit of a lift.

Peter -- do you think the tradeoff of extra files and symlinks and all
that is worth it for the possibility of confusing a small number of
people on Windows? My preference would be to have a cleaner web presence
on GitHub, which will effect more users. If README.md is too terse or
confusing, we could do README.markdown.

In terms of reStructuredText versus Markdown, I don't have a strong
opinion. I get the sense GitHub better supports Markdown but as long as
the rst looks fine it doesn't matter.

Brad


> 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
> _______________________________________________
> Biopython-dev mailing list
> Biopython-dev at lists.open-bio.org
> http://lists.open-bio.org/mailman/listinfo/biopython-dev