> These 2 produce IDENTICAL output.
This is my single biggest complaint about reStructuredText. You create headings by putting underlines and (optional!) overlines around the section heading text. But all of the following are valid title adornment characters:
! " # $ % & ' ( ) \* +
, - . / : ; < = > ? @
[ \ ] ^ _ ` { | } ~
So in each doc you have to figure out the H1, H2, H3 formatting separately. E.g. in one doc it's: ==
H1
==
Normal text
--
H2
--
Whereas in another it might be: H1
~~
Normal text
!!
H2
!!