[arrow] branch master updated: ARROW-16709: [Docs][Python] Add how to run doctests to the developer guide (#13325)

[ap...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

apitrou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git


The following commit(s) were added to refs/heads/master by this push:
     new c52a04faf6 ARROW-16709: [Docs][Python] Add how to run doctests to the developer guide (#13325)
c52a04faf6 is described below

commit c52a04faf6b1c630b40d015575af6a97b656787c
Author: Alenka Frim <Al...@users.noreply.github.com>
AuthorDate: Wed Jun 8 10:48:17 2022 +0200

    ARROW-16709: [Docs][Python] Add how to run doctests to the developer guide (#13325)
    
    This PR adds content to the documentation about running `doctest` on PyArrow docstring examples.
    
    Lead-authored-by: Alenka Frim <fr...@gmail.com>
    Co-authored-by: Alenka Frim <Al...@users.noreply.github.com>
    Signed-off-by: Antoine Pitrou <an...@python.org>
---
 docs/source/developers/python.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/source/developers/python.rst b/docs/source/developers/python.rst
index 6cd19788de..9f8280c22a 100644
--- a/docs/source/developers/python.rst
+++ b/docs/source/developers/python.rst
@@ -105,6 +105,32 @@ The test groups currently include:
 * ``s3``: Tests for Amazon S3
 * ``tensorflow``: Tests that involve TensorFlow
 
+Doctest
+-------
+
+We are using `doctest <https://docs.python.org/3/library/doctest.html>`_
+to check that docstring examples are up-to-date and correct. You can
+also do that locally by running:
+
+.. code-block::
+
+   $ pushd arrow/python
+   $ python -m pytest --doctest-modules
+   $ python -m pytest --doctest-modules path/to/module.py # checking single file
+   $ popd
+
+for ``.py`` files or
+
+.. code-block::
+
+   $ pushd arrow/python
+   $ python -m pytest --doctest-cython
+   $ python -m pytest --doctest-cython path/to/module.pyx # checking single file
+   $ popd
+
+for ``.pyx`` and ``.pxi`` files. In this case you will also need to
+install the `pytest-cython <https://github.com/lgpage/pytest-cython>`_ plugin.
+
 Benchmarking
 ------------