How do we want to provide docs for REST API?

I'll try to list some different options:

• we could use sphinxcontrib and the flask plugin to provide documentation through sphinx and rtfd.org
• @hellais in Rest Api #52 suggests to use Swagger for documenting API. I already use it and I like this tools.
  We could expose Swagger-UI through flask under something like /api/docs but in this case the only way to read the API docs is to run libreant. To resolve this problem we could try some way:
  • thanks to Swagger-codegen it's also possible to generate static html docs
  • I found also sphinx-swagger that seems to convert swagger specs into sphinx docs.

What option do you like the most?
Do you know other tools/ways to documenting the REST API?