Rst(ReStructuredText) symbols' and overlines' effect

Question

I am trying to use rst for documentation, but I am not able to find good and definite reference. What is the order of symbols for underline and overline in font-size order (ascending/descending)? I have read wikipedia article that mentions

Header
======

Sub-header
----------

But when I try this in an online rst editor(I am not sure how trustworthy this is) and change order, the font-size(header order) seems to depend on the order in which these headers come(i.e. first one gets <h1>, next one gets <h2> etc.) irrespective of the symbols (- or =) used.

Also, when I use them for overlines, they have different font-sizes for those with only underline and those with both underline & overline(useing same symbol, - or =). In other words, overline also affects the output. If other symbol is used, that too affects the font-sizes. And to increase the confusion, I have seen the use of symbols like * and # too and they too seem to affect the sizes.

But, on trying with all of them, I am still not able to map any of these symbols to a definite heading/font-size. I am also not able to understand what effect does the order of their appearance has. And not to forget, how does the use of overlines play in?

Answer 1

In reStructuredText (hereby reST), there are 2 variants of title markup:

with underline symbols
@@@@@@@@@@@@@@@@@@@@@@

and

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
with both under and overline symbols
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

There is no pre-defined order between them, the rule is the first occurrence is the most significant title, the second type to occur will be the second significant title, etc.

Also as you suspected the same is true for each symbol you choose for underlining or under and overlinning.

You can find some convention as what symbol to use, but it is more common sence than anything else, so go with what works best for you.

Answer 2

It's not a very clear answer but if anyone gets the same doubt again, I hope this might be helpful.

It seems that the order is more important than the symbols used. My observation is too strange to clarify easily in words- the first 2 symbols will have their effect toggled on font size.i.e. the first occurrence gives the largest text size(with or without overline). The 2nd symbol will have one less size( which is equal to the first symbol when toggled overline). when toggled the overline of this symbol, gives text size that will be equal to the first symbols(first occurrence) i.e. the largest. After these first two, next two symbols give decreasing sizes. After this, no symbol has any effect.

I will later take a look at the code of documentation utilities of python which will clarify.