fix: indent Google-style summary lines in prepare_docstrings.py

[TaiSakuma]

Summary

Sphinx supports Google-style docstrings via sphinx.ext.napoleon. However,
Awkward doesn't use it in the standard way. Because Awkward has compiled C++
extensions (awkward-cpp), the docs can't import the package at build time
as sphinx.ext.autodoc requires. Instead, docs/prepare_docstrings.py
parses source files with ast and calls sphinx.ext.napoleon.GoogleDocstring
directly, then applies regex-based transforms for cross-references, code
blocks, and directive indentation (see #187, #158).

This custom processor indents :param, :type, :returns, and :raises
directives to sit inside the RST .. py:function:: block, but it did not
handle Google-style summary lines. Napoleon outputs summary text at column 0,
causing it to render outside the function directive in the built docs. This
is likely why summary lines have been absent from Awkward docstrings.

This PR adds a targeted regex to dodoc() that indents only the summary
paragraph (non-whitespace text before the first :param directive) by 4
spaces. The regex is scoped narrowly to avoid affecting docstrings without
a summary line.

Tests

Two dodoc() unit tests are added, following the existing test_signature_*
pattern:

• test_dodoc_no_summary — verifies existing format is unchanged (no
  regression)
• test_dodoc_with_summary — verifies the summary line is indented

Full document comparison

All RST files were regenerated with and without the fix and diffed. The only
difference across the entire generated documentation was the intended change:
the summary line in ak.flatten.rst gaining 4-space indentation.

This branch includes the commit from #3946 (ak.flatten docstring update).

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

[github-actions]

The documentation preview is ready to be viewed at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR3947

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.28%. Comparing base (4479e16) to head (c9bc91b).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

Files with missing lines	Coverage Δ
src/awkward/operations/ak_flatten.py	94.64% <ø> (ø)

... and 7 files with indirect coverage changes

[TaiSakuma]

@ianna I opened altarnative PR with another solution: #3948.

There is a new Sphinx extension from Read the Docs that solves the same problem as prepare_docstrings.py does: https://github.com/readthedocs/sphinx-autoapi . The other PR uses that extension.

[TaiSakuma]

The alternative solution #3948 has been merged.