Intelligently determine what file to render a README from if README.* isn't present

[avar]

(It doesn't look like this is part of the github/markup code, so I couldn't patch this)

Currently a lot of projects have some sort of embedded documentation that's easy to find, but GitHub doesn't find and display it.

Examples include:

• This project, which has only a single file, which includes embedded POD.
• This project. Which has a README.pod generated from lib/Hailo.pm

It would be nice if GitHub's logic for finding documentation to display in the main page of the project was a bit more permissive than just displaying glob("README_"). E.g. by seeing that the project has one main file that has embedded docs, or that the "main module" of a project has docs (e.g. for Perl code figure out that it's the top-level class in lib/, which could be just find lib -type f -name '_.pm' | head -n 1 for the common case).

[defunkt]

Dupe of #3

[avar]

I don't think so, no (and I filed #3). That one is about what to do with README, this one is more far reaching. It's about reaching potentially deep inside the project to extract text to render as the readme.

[kneath]

We generally try and stray away from any language/framework-specific additions to GitHub. Digging into a project and parsing documentation out of a code file doesn't sound appealing to me at all.

I'd much rather see people put READMEs in their repos — that helps people who aren't familiar with language-specific paradigms (lib/Halio.pm) to understand what they're looking at whether it's hosted on GitHub, downloaded from source, or hosted on another code hosting site.

[avar]

Sure, a README is sometimes nice. But in a lot of cases that means committing duplicate documentation to the Git repository.

Not everyone does that, so sometimes I have to go dig around in the repository when I get "We couldn't find a README for this repository". It'd be nice if the renderer were smarter when choosing what to pick out.