docs: add experimental API to sphinx docs

Move the documentation from the module docstring into the documentation
proper. Fix up a few typos on the way.