section heading in function doc string triggers error: Unexpected section heading

[Phillip-M-Feldman]

Describe the bug

The presence of a section heading in a doc string triggers the error "unexpected doc string". Is this something that is supposed to work? When a function's doc string is very long, the ability to divide it into sections is essential.

How to Reproduce

Put a section heading in the doc string of a function or method.

Expected behavior

No response

Your project

N/A

Screenshots

No response

OS

Windows 10

Python version

3.8.8

Sphinx version

5.2.2

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[AA-Turner]

Hi Phillip, please provide a minimal reproducer with Sphinx 5.2.3 (ideally a single .rst file and a minimal conf.py)

A

[Phillip-M-Feldman]

A minimal reproducer is attached.
Sphinx_bug_demo.zip

[AA-Turner]

Minimal reproducer:

import shutil
from pathlib import Path

from sphinx.cmd.make_mode import run_make_mode

Path("conf.py").write_text('''\
''', encoding="utf-8")

Path("index.rst").write_text('''\
.. py:function:: func()

   Overview
   --------
   
   Lorem ipsum dolar sit amet
''', encoding="utf-8")

shutil.rmtree("_build", ignore_errors=True)
run_make_mode(["html", ".", "_build", "-anETW"])

A