text of warning / note directives should be rendered in a box or/and in another color. Currently it looks like this: ~~~ note This is a note ~~~ but it should look somehow like here -->  see also --> https://sublime-and-sphinx-guide.readthedocs.io/en/latest/notes_warnings.html IMHO this would be a big improvement for the readability of technical documentation with less effort for you for the implementation.