in particular:

- remove defintion lists (Description/Example)
- examples as code blocks::
- argument names as *emphasis*
- ``literals``

Ref: doc/README.WRITING_RST.rst