Adjustments to markdown docs in order to get a better pandoc conversion.

Just for review, not intended to be merged in at this point.

I have done some minor adjustments wrt. backticks and minor format issues that caused a bit of trouble in the conversion.

Doing a

`pandoc -f markdown_github+raw_html README.md -o index.rst`

is more or less doing a perfect transformation - getting warnings about not using local images, but that is not a biggie to solve. I need to add some table css to the sphinx theme to get a similar setup as the on github.