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.

[bhavanaeh]

I went with a .. note:: block to make this stand out, but happy to change it to inline text if that's preferred.

[github-actions]

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