News for hackers. Stuff that matters.
Re:Show HN: Instant documentation site for Github projects by LeafStorm on Wednesday January 25, 2012 @06:12PM (#3512163)
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.

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 all their project's documentation into the README and the examples instead of having proper narrative and API documentation.

Re:Show HN: Instant documentation site for Github projects by ricardobeat on Wednesday January 25, 2012 @06:25PM (#3512210)
I prefer all-encompassing READMEs over incomplete scattered documentation.
Re:Show HN: Instant documentation site for Github projects by stock_toaster on Wednesday January 25, 2012 @06:35PM (#3512243)
I think all-in-one-README works well for some things, but some of our projects at work would result in HUUUGE readme files. Not so pleasant if those were a single file. We have started using gollum-site[1] for our stuff that grows beyond a medium size length.

The single-long-readme length issue appears to be alleviated by the nav construction in documentup though. Pretty slick.

https://github.com/dreverri/gollum-site

Re:Show HN: Instant documentation site for Github projects by code_pockets on Wednesday January 25, 2012 @07:21PM (#3512367)
Agreed, though I'm guilty as charged.

This has led me to re-think the README/documentation problem, and gave me an app idea. A little web app that allows the user to build a proper README with a template. Sort of those build a resume apps, but for README files. I plan on building it at the end of February, after I ship my current foss project.

Re:Show HN: Instant documentation site for Github projects by sequoia on Wednesday January 25, 2012 @04:39PM (#3511871)
This is pretty cool and I know non-javascript users (besides some screen readers) aren't as common but you've gotta give something 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.

Looks nice tho!!

Re:Show HN: Instant documentation site for Github projects by jeromegn on Wednesday January 25, 2012 @04:43PM (#3511882)
Re:Show HN: Instant documentation site for Github projects by acdha on Wednesday January 25, 2012 @06:37PM (#3512252)
If you're looking for a more mature service, particularly if you're already using Sphinx, checkout http://readthedocs.org/ which includes nice things like full text search, PDF generation, versioning, etc. and supports other hosting sites and version control systems.
Re:Show HN: Instant documentation site for Github projects by jeromegn on Wednesday January 25, 2012 @04:05PM (#3511740)
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.

There's still much to do. This is an MVP.

Re:Show HN: Instant documentation site for Github projects by shareme on Wednesday January 25, 2012 @04:33PM (#3511843)
this is good.. have you shown it to the github guys and gals yet?
Re:Show HN: Instant documentation site for Github projects by jeromegn on Wednesday January 25, 2012 @04:36PM (#3511856)
I haven't. Just having some fun, built this to hone my front-end skills and because I needed it.
Re:Show HN: Instant documentation site for Github projects by kmfrk on Wednesday January 25, 2012 @08:14PM (#3512479)
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.

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.

Re:Show HN: Instant documentation site for Github projects by conesus on Wednesday January 25, 2012 @06:19PM (#3512188)
Heard about this on Twitter, and in under 3 minutes had this: http://samuelclay.github.com/NewsBlur. Gorgeous and very easy to install. Kudos!
Re:Show HN: Instant documentation site for Github projects by huguesalary on Thursday January 26, 2012 @02:22PM (#3515531)
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.
Re:Show HN: Instant documentation site for Github projects by jeromegn on Thursday January 26, 2012 @04:21PM (#3516054)
I'm thinking of adding an option to Bring Your Own Markdown. This has a few implications that I need to code for though.
Re:Show HN: Instant documentation site for Github projects by lux on Wednesday January 25, 2012 @07:18PM (#3512358)
Cool, but the menu gets in your way when you zoom on iPhone.
Re:Show HN: Instant documentation site for Github projects by sequoia on Wednesday January 25, 2012 @04:40PM (#3511876)
Oh, also, what do you mean by "deep linking"? I'm not sure what you'd deep-link to... is anything loaded dynamically?
Re:Show HN: Instant documentation site for Github projects by jeromegn on Wednesday January 25, 2012 @04:44PM (#3511885)
I mean, being able to link to a specific point (like a H2 or H3) in the README and have the page actually scroll there. Right now I don't think it works (or at least it's completely untested.)
Re:Show HN: Instant documentation site for Github projects by Klonoar on Wednesday January 25, 2012 @07:01PM (#3512323)
Why doesn't github just do this themselves
Re:Show HN: Instant documentation site for Github projects by shpoonj on Wednesday January 25, 2012 @09:07PM (#3512615)
This would be great if it had a reliable style sheet.

This one, however, breaks on iOS, for example.

May I recommend BS2?