In the documentation guide, in which docs should go where, in the first example, it says that API docs should be stored in reStructuredText. This will probably confuse people who define APIs in Swagger. Swagger APIs can be automatically converted in Sphinx, but the example should be something simpler.