

Show HN: Instant documentation site for Github projects - jeromegn
http://documentup.com/

======
LeafStorm
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.

~~~
ricardobeat
I prefer all-encompassing READMEs over incomplete scattered documentation.

~~~
stock_toaster
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>

------
sequoia
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!!

~~~
jeromegn
Good point. Noted here: <https://github.com/jeromegn/DocumentUp/issues/2>

------
acdha
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.

------
jeromegn
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.

~~~
shareme
this is good.. have you shown it to the github guys and gals yet?

~~~
jeromegn
I haven't. Just having some fun, built this to hone my front-end skills and
because I needed it.

------
kmfrk
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.

------
conesus
Heard about this on Twitter, and in under 3 minutes had this:
<http://samuelclay.github.com/NewsBlur>. Gorgeous and very easy to install.
Kudos!

------
huguesalary
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.

~~~
jeromegn
I'm thinking of adding an option to Bring Your Own Markdown. This has a few
implications that I need to code for though.

------
lux
Cool, but the menu gets in your way when you zoom on iPhone.

------
sequoia
Oh, also, what do you mean by "deep linking"? I'm not sure what you'd deep-
link to... is anything loaded dynamically?

~~~
jeromegn
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.)

------
Klonoar
Why doesn't github just do this themselves

------
shpoonj
This would be great if it had a reliable style sheet.

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

May I recommend BS2?

