since I found myself wonder how it works
Converting some of the rst documentation to markdown. Attempted to preserve whitespace and line breaks to minimize cosmetic change.