add some docs to methods
correct rest syntax
add sphinx docs directive