GH-49503: [Docs][Python] Documenting .pxi doctests are tested via lib.pyx

[bhavanaeh]

Rationale for this change

Running python -m pytest --doctest-cython directly on .pxi files doesn't work because Cython .pxi files are included in .pyx files at compile time. This isn't documented, which could potentially confuse contributors.

Please see discussion in #49279 (comment) by @AlenkaF for additional context.

What changes are included in this PR?

Added a note to the Doctest section of the Developing PyArrow documentation explaining that:

• .pxi files cannot be tested directly with --doctest-cython
• Doctests should be run on the .pyx file they are included in (e.g., lib.pyx)
• Errors will appear under the .pyx file, not the original .pxi filename

Are these changes tested?

Documentation-only change. No code changes.

Are there any user-facing changes?

No.

• GitHub Issue: [Docs][Python] Document that .pxi doctests are tested via lib.pyx #49503

[github-actions]

⚠️ GitHub issue #49503 has been automatically assigned in GitHub to PR creator.

[github-actions]

⚠️ GitHub issue #49503 has been automatically assigned in GitHub to PR creator.

[AlenkaF]

@github-actions crossbow submit preview-docs

[github-actions]

Revision: ecff1a1

Submitted crossbow builds: ursacomputing/crossbow @ actions-bfd9f4b8a6

Task	Status
preview-docs

[AlenkaF]

Thanks for the PR!
Adding one comment from my side.

[bhavanaeh]

@AlenkaF thanks for the comment, addressed!

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 2 benchmarking runs that have been run so far on merge-commit 8a8e574.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details. It also includes information about 9 possible false positives for unstable benchmarks that are known to sometimes produce them.