GH-28859: [Doc][Python] Use only code-block directive and set up doctest for the python user guide

ci/scripts/python_test.sh

@@ -70,3 +70,8 @@ export PYARROW_TEST_S3
 
 # Testing PyArrow
 pytest -r s ${PYTEST_ARGS} --pyargs pyarrow
+
+# Testing RST documentation examples (if PYTEST_RST_ARGS is set)
+if [ -n "${PYTEST_RST_ARGS}" ]; then
+  pytest ${PYTEST_RST_ARGS} ${arrow_dir}/docs/source/python
+fi

compose.yaml

@@ -1530,6 +1530,7 @@ services:
       BUILD_DOCS_CPP: "ON"
       BUILD_DOCS_PYTHON: "ON"
       PYTEST_ARGS: "--doctest-modules --doctest-cython"
+      PYTEST_RST_ARGS: "--doctest-glob=*.rst"
     volumes: *conda-volumes
     command:
       ["/arrow/ci/scripts/cpp_build.sh /arrow /build &&

docs/source/developers/python/development.rst

@@ -127,6 +127,24 @@ for ``.py`` files or
 for ``.pyx`` and ``.pxi`` files. In this case you will also need to
 install the `pytest-cython <https://github.com/lgpage/pytest-cython>`_ plugin.
 
+Testing Documentation Examples
+-------------------------------
+
+Documentation examples in ``.rst`` files under ``docs/source/python/`` use
+doctest syntax and can be tested locally using:
+
+.. code-block::
+
+   $ pushd arrow/python
+   $ pytest --doctest-glob="*.rst" docs/source/python/file.rst # checking single file
+   $ pytest --doctest-glob="*.rst" docs/source/python # checking entire directory
+   $ popd
+
+The examples use standard doctest syntax with ``>>>`` for Python prompts and
+``...`` for continuation lines. The ``conftest.py`` fixture automatically
+handles temporary directory setup for examples that create files.
+
+
 Debugging
 =========