> it sounds well in practice, until you discover Sphinx. Sphinx does a better job in a more generic way.
As someone who started to write our API docs in Sphinx (with an appropriate HTTP extension) but saw this and was about to start using it, your comment may have saved me a few hours of work.
Why do you say that Sphinx is better, though? I found that, to document an API, you can either document the code or the API (HTTP-side). Sphinx can do both, but the useful part (HTTP-side documentation) has to be rewritten from scratch and updated separately (unlike the code docs, which can be generated from the docstrings).
For documenting code, Sphinx has the advantage that you can use it for cool stuff like testing the sample code provided. See here: http://sphinx.pocoo.org/ext/doctest.html
But you won't get away with just docstrings. Good documentation also includes a high-level overview of the API, history of changes, a glossary of terms, etc...
It does have a slight learning curve, but it is very extensible while providing enough out-of-the-box already, and some people have been using it to write entire books.
That's exactly what I use too, it's not perfect but it gets you 95% of the way there. I didn't find it too hard to learn, I just picked up the examples and was on my way to writing the docs within a few minutes.
As someone who started to write our API docs in Sphinx (with an appropriate HTTP extension) but saw this and was about to start using it, your comment may have saved me a few hours of work.
Why do you say that Sphinx is better, though? I found that, to document an API, you can either document the code or the API (HTTP-side). Sphinx can do both, but the useful part (HTTP-side documentation) has to be rewritten from scratch and updated separately (unlike the code docs, which can be generated from the docstrings).