reorder documentation: theory first
sphinx doc fixes