Leave trailing line break in reST directives

[howamith]

Closes #384.

Feels a little clunky adding a trailing line break when processing reST directives, to then have to remove it again for reST directives in code blocks, but I couldn't see any other way. Figured I'd submit a PR anyway for feedback and go from there.

[kernc]

Clunky indeed, but unless we have a way to fix the regex:

pdoc/pdoc/html_helpers.py

Lines 325 to 328 in 4aa70de

	substitute = partial(re.compile(r'^(?P<indent> *)\.\. ?(\w+)::(?: *(.*))?'
	r'((?:\n(?:(?P=indent) +.*| *$))*)', re.MULTILINE).sub,
	partial(_ToMarkdown._admonition, module=module,
	limit_types=limit_types))

I don't have a really better idea.

[howamith]

Another possibly way of neatening this up would be to somehow detect the context of where the reST directive is (i.e whether or not it's within a code block) and only add the trailing new-line where appropriate. This context could be detected in, or outside of and passed in, to _ToMarkdown._admonition().

[kernc]

Another way would be to actually amend the culprit regex. It's posed as:

^(?P<indent> *)\.\. ?(\w+)::(?: *(.*))? ((?:\n(?:(?P=indent) +.*| *$))*)

for its second line to matche any indented paragraphs (separated with a line break). E.g.:

Outside admonition. .. warning:: Title First paragraph. Second paragraph. # Our regex matches this final line break. But if it didn't ... Outside admonition.

As can be seen here (trailing \n is visible in the "Export Matches" JSON).

I think we could rewrite the regex to not consume the line break unless another indented paragraph follows it ... 🤔

[howamith]

Not quite fully isolated to just changing the regex, but I think that's the closest you'll get (though I'm by no means an expert when it comes to regex!).

Let me know what you think - if you're happy with that then I'll squash the redundant commits and let you merge :)

[kernc]

Excellent find of the regex! Many thanks! 🍰