One nice thing about GitHub and Bitbucket's focus on the project's README is that more software projects are providing a good, instantly-readable summary of their project in the README instead of making you have to go elsewhere to find out what it's all about and how to get started.<p>One not-so-nice thing about GitHub and Bitbucket's focus on the project's README is that I have noticed several projects that dump <i>all</i> their project's documentation into the README and the examples instead of having proper narrative and API documentation.
This is pretty cool and I know non-javascript users (besides some screen readers) aren't as common but you've gotta give <i>something</i> to people w/o JS, even if it's just "Please turn on javascript. Read text version here a:github.com/user/project/README.md" or something. I understand modern web apps not always degrading but this is almost 100% flat text, there should be some way to serve all users.<p>Looks nice tho!!
If you're looking for a more mature service, particularly if you're already using Sphinx, checkout <a href="http://readthedocs.org/" rel="nofollow">http://readthedocs.org/</a> which includes nice things like full text search, PDF generation, versioning, etc. and supports other hosting sites and version control systems.
I needed it for one of my projects and so I whipped up this simple documentation generator. It takes your README.md and turns it into an easier to navigate documentation site. Meant to be used on a gh-pages branch.<p>There's still much to do. This is an MVP.
Are you considering adding SmartyPants to the formatting? Then again, SmartyPants takes options for which kind of formatting you want to use, and, at least in the Python version, I never go with the default one, so it's probably useless to me without the ability to specify my specific formatting.<p>I really hope this gets a lot of attention; it's one of the best things I have seen on Hacker News in months, and I'm surprised we haven't even hit triple-digit karma for it.
Heard about this on Twitter, and in under 3 minutes had this: <a href="http://samuelclay.github.com/NewsBlur" rel="nofollow">http://samuelclay.github.com/NewsBlur</a>. Gorgeous and very easy to install. Kudos!
Great project, easy to install, beautiful presentation. Why limiting to GH pages though? I would love to use it with my markdown documentation, but my project is not on github.