The last few days I spent quite a lot of time with trying to write a Sphinx extension that allows to generate documentation for functions with keyword arguments from a jsonschema.
Sphinx is really fantastic, it is a tool that makes it relatively efficient to write useful documentation. Its autodoc extension allows to extract a lot of information from the sources, which is DRY, leads to slower documentation rot and quite efficient. It is based on docutils and restructuredText, which is a lightweight markup language similar to markdown, but with a larger scope. It is not just an abbreviation for HTML, but has a DOM and is designed to be extensible.
The design of restructuredText seems really solid, but its documentation is not really good. I ended up reading the source to gather the information I needed, and this was so painful, that I ended up hacking around the proper solution with Sphinx' preprocessing hooks and regular expressions.
This is a shame, I have a few problems, where the extensibility of reST would really come in handy, but the lack of usable documentation scares me.