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 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.
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.
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.
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 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 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.)
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.
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
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.
Looks nice tho!!
There's still much to do. This is an MVP.
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.
This one, however, breaks on iOS, for example.
May I recommend BS2?