Doc: change rst to markdown

and clean typos
Doc: small corrections
Doc: small update
Doc: change note and warning to array

they were not rendered with github markodwn, so I changed it to an array
even if it is not as good as rst ..note or ..warning blocks
Merge pull request #399 from antoine-de/doc_to_md

Doc to md