The following seem like a good idea:
- Make the API documentation accessible through requests for HTML with GET on the API URLs.
- Make the documentation interactive (able to test GETs/PUTs etc from the documentation pages).
- Make the source material obviously linked to the code.
- Share the source material with more general documentation tools.
I tried using the httpdomain sphinx extension (which includes Flask extension), but did not find it sufficiently expressive. Preferred instead to keep more flexibility.
- Write reST in separate files
- Tell Sphinx to compile them into Flask's
- Run make_apidocs.sh to convert the reST into HTML.
- The examples are generated using the programoutput extension to run against the server, thus automatically ensuring accuracy. Beware that the extension caches outputs...
- Redirect HTTP GET for
text/htmlto the appropriate page
See apidocs for details. Beware that Bitbucket does not understand all the Sphinx directives so it is best to browse the
.rst files in raw mode (or just download the repo and view locally).