Maxime from Algolia here. There is a lot of things out there to build docs. (Sphinx, readme.io, jekyll, middleman, web frameworks, ...).

All those tools are good at what they do. When you want to do something very specific/custom, you will always end up needing something outside the scope of those products.

So far at Algolia, middleman is the one we're using for our main documentation. We had to tweak it a lot and reimplement some parts but it works and we should be able to keep it running for a while.

https://apiblueprint.org/tools.html and https://swagger.io/ are open documentation standards for APIs with editors, renderers and tools to mock a test environment.

For my own API (https://geocoder.opencagedata.com/api) it's hand-coded because the output of the tools are too complex when you have only 1-2 methods.