I think you have a valid point (other than in the case of the Vagrant docs, which I absolutely detest [0]).
The simplest way to make good-looking docs might just be to 'just use Sphinx' (as does Flask, mentioned and http://docs.python.org/ and [many others][1].
The docs are a necessity to make up for the shoddy, inconsistent patchwork that is their language design, but they are damned well designed and easy-to-use for the wading through flat scope that is required by those who use the language.
[0]: Disappearing sidebar when you resize to narrow, huge amounts of spacing everywhere and sidebar names that can't be expanded without navigating to their root. :/
Ooooh the PHP ones are even better than they used to be, I hadn't checked in a while. I have always loved the user comments in docs idea. I've noticed so many bugs, gotchas and idiomatic patterns simply by looking at those comments. I bet it gives the devs a good idea on what to work on next, too. It didn't used to have votes which was bad because it perpetuated bad advice sometimes, but now it seems they have that too!
The simplest way to make good-looking docs might just be to 'just use Sphinx' (as does Flask, mentioned and http://docs.python.org/ and [many others][1].
Another example of amazing docs (they've always been pretty decent, but amazing in their most recent style) are the PHP docs: http://www.php.net/manual/en/function.pg-affected-rows.php
The docs are a necessity to make up for the shoddy, inconsistent patchwork that is their language design, but they are damned well designed and easy-to-use for the wading through flat scope that is required by those who use the language.
Similarly, styles based on YARD/codo (http://coffeedoc.info/github/coffeedoc/codo/master/) are pretty nice for API references.
[0]: Disappearing sidebar when you resize to narrow, huge amounts of spacing everywhere and sidebar names that can't be expanded without navigating to their root. :/
[1]: http://sphinx-doc.org/examples.html