Infra: add newlines so admonition text is shown

[hugovk]

Follow on from #3682.

Re: #3682 (comment)

And remove text duplicating that inserted by the template.

Previews:

• https://pep-previews--3756.org.readthedocs.build/pep-0003/
• https://pep-previews--3756.org.readthedocs.build/pep-0009/
• https://pep-previews--3756.org.readthedocs.build/pep-0042/
• https://pep-previews--3756.org.readthedocs.build/pep-0103/
• https://pep-previews--3756.org.readthedocs.build/pep-0204/
• https://pep-previews--3756.org.readthedocs.build/pep-0206/
• https://pep-previews--3756.org.readthedocs.build/pep-0209/
• https://pep-previews--3756.org.readthedocs.build/pep-0210/
• https://pep-previews--3756.org.readthedocs.build/pep-0211/
• https://pep-previews--3756.org.readthedocs.build/pep-0215/
• https://pep-previews--3756.org.readthedocs.build/pep-0216/
• https://pep-previews--3756.org.readthedocs.build/pep-0220/
• https://pep-previews--3756.org.readthedocs.build/pep-0224/
• https://pep-previews--3756.org.readthedocs.build/pep-0225/
• https://pep-previews--3756.org.readthedocs.build/pep-0239/
• https://pep-previews--3756.org.readthedocs.build/pep-0241/
• https://pep-previews--3756.org.readthedocs.build/pep-0242/
• https://pep-previews--3756.org.readthedocs.build/pep-0363/
• https://pep-previews--3756.org.readthedocs.build/pep-0426/

---

📚 Documentation preview 📚: https://pep-previews--3756.org.readthedocs.build/

[malemburg]

LGTM

[Yhg1s]

The need for a newline feels a bit like a footgun, is there a way to address that, or have it show up as a lint warning?

[hugovk]

Will check into that before doing the next batch, it might be something to do with how these custom directives set admonition_pre_template/admonition_pre_text: https://github.com/python/peps/pull/3682/files#diff-9289f0259c1905b9816aa119d9e3e457cadd059c916a83de500732f15ae8109dR130

[encukou]

AFAIK that's normal ReST syntax: the blank line separates a directive's arguments/options from its content.
Since admonitions have final_argument_whitespace = True, this block is treated as (a continuation of) the argument, that is, link_content.

I don't see a good way to disable the argument-continuation/option block, short of parsing the entire directive manually (using self.block_text in run).

Perhaps it'd be best to warn/error on suspicious cases:

• self.content is empty but link_content is not
• self.content is empty and link_content is multi-line
• there's some link_content but the template doesn't expect it

[pradyunsg]

I wrote a long blurb here and realised it would be easier to just draft up the change -- so, filed #3765 as a potential way forward here.