rst: runnableExamples affects rst underline headings

[timotheecour]

Example

## Basic Usage
## ===========
##
## some comment
##
## Lists1
## ------
##
## Lists2
## ------
##
runnableExamples:
  discard

## Lists3
## ------
##
runnableExamples:
  discard


## Lists4
## ------
runnableExamples:
  discard


## # Lists5
runnableExamples:
  discard


## ## Lists6
runnableExamples:
  discard

##[

# Lists7
## List 8
## List 9
foo
]##

Current Output

Expected Output

• Lists4 ------ is a bug, should appear as List2
• Lists3 is a bug, should appear as List2

everything else works fine

workaround

use markdown style prefix form (list5,...,list9) instead of underline form as was done in #16981
(not really a workaround since prefix form is IMO better style, more familiar for markdown users, and easier to use since you don't have to match the length of title with underline markers)

Additional Information

1.5.1 0d34345
/cc @a-mr since you've fixed many rst issues recently :)

[a-mr]

there are 2 separate problems here:

• (easy) when adornment is at the end of file/string then it's parsed as normal text Lists4-------
• (hard) state is not shared between rstParse invocations for *.nim file. Essentially all RST fragments inside 1 nim file are parsed like separate documents! That's why RST parser determines first section in every doc comment as 1-level heading. I think it's always been present, other information is not shared b/w doc fragments also, e.g. this does not work as expected:

  ## Ref lnk_.
  discard
  ## .. _lnk: http://example.org/

I almost have a PR for the easy one.

Regarding the hard one - I think it would be logical to consider all doc comments as parts of one document, at least in sharing SharedState. @narimiran do you agree?

[timotheecour]

Regarding the hard one - I think it would be logical to consider all doc comments as parts of one document, at least in sharing SharedState.

+1 to that. This may also help with nim-lang/RFCs#125 (DRY doc links) and the WIP RFC timotheecour#228 (lightweight refs in docs).