Agreed. I'm currently running a site over at http://readthedocs.org/ which is meant to be your one-stop shop for Sphinx documentation. It has most of the big python projects on it, and hopefully as sphinx gets more popular, it will attract others as well. For example, we are mirroring the Varnish docs.
We also had a kick-ass designer help us on it, so the site actually looks rather pretty.
I've had a number of people tell me that RTD has been something that has spurred them to write documentation, so I'm really happy with the results thus far.
Ok, Rails Guides definitely deserves mention for being one of the prettiest sources of documentation, but I don't know that it really deserves mention as being a great example of good documentation. I mean it isn't bad, but django's documentation beats the pants off of it.
I guess without hearing my talk, this might be confusing. Rails Guides is in there as an example of Tutorial type documentation and a way to leverage your project's website.
This presentation was prepared for a Ruby conference, so the examples were geared toward the audience (ruby & rails centric).
More importantly though: When's the last time you used Rails Guides? There was a time when Django's documentation was light years better than anything Rails prepared, but I would very much disagree saying Rails Guides are poor in comparison today.
As someone who originally came from python and recently learned rails (well, still in the process) using the official docs and the railsbook I have to say: Sorry but yes, the Rails docs (at least the ones I have found) are poor in comparison.
And it gets only worse when you look beyond Rails; documentation in the ruby realm (gems et al) is almost always lacking in quantity and underwhelming in quality to a former pythonista.
Admittedly it's a bit of an unfair comparison, considering python docs are - on average - the best I've ever seen. And considering python is a bit easier to document formally due to less magic in the language.
But it's also a mindset thing.
Python has doc-strings and doc-test baked right into the language. Sphinx and epydoc are so ridiculously good, it's not funny.
On the ruby side documentation seems more like an afterthought. RDoc itself is poorly documented (oh the irony!), and the only tool to bake readable output from it (YARD) is a fairly recent invention. I haven't found an equivalent to sphinx, yet.
The obsession that the python community applies to documentation seems to be spent on testing-tools in the ruby camp. This is, however, a rather unfortunate choice of priorities when you look at the (lack of) documentation for even the most popular testing tools (e.g. RSpec)...
> Rails Guides is in there as an example of Tutorial type documentation and a way to leverage your project's website.
But see, that's what kept it from being really good in my opinion. Sure, it's an example of good tutorial-based documentation. The tutorial/reference divide seems kind of artificial to me though. It leaves you with documentation you can use as a beginner and documentation you can use as an advanced user, but nothing to help you move between the two. In contrast, django's documentation tends to be a good mix between the two.
We also had a kick-ass designer help us on it, so the site actually looks rather pretty.
I've had a number of people tell me that RTD has been something that has spurred them to write documentation, so I'm really happy with the results thus far.