| .. Licensed to the Apache Software Foundation (ASF) under one | |
| .. or more contributor license agreements. See the NOTICE file | |
| .. distributed with this work for additional information | |
| .. regarding copyright ownership. The ASF licenses this file | |
| .. to you under the Apache License, Version 2.0 (the | |
| .. "License"); you may not use this file except in compliance | |
| .. with the License. You may obtain a copy of the License at | |
| .. http://www.apache.org/licenses/LICENSE-2.0 | |
| .. Unless required by applicable law or agreed to in writing, | |
| .. software distributed under the License is distributed on an | |
| .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| .. KIND, either express or implied. See the License for the | |
| .. specific language governing permissions and limitations | |
| .. under the License. | |
| Building the Python Cookbook | |
| =========================== | |
| The python cookbook uses the Sphinx documentation system. | |
| Running ``make py`` from the cookbook root directory (the one where | |
| the ``README.rst`` exists) will install all necessary dependencies | |
| and will compile the cookbook to HTML. | |
| You will see the compiled result inside the ``build/py`` directory. | |
| Testing Python Recipes | |
| ====================== | |
| All recipes in the cookbook must be tested. The cookbook uses | |
| ``doctest`` to verify the recipes. | |
| Running ``make pytest`` from the cookbook root directory | |
| will verify that the code for all the recipes runs correctly | |
| and provides the expected output. | |
| If the environment variable ``ARROW_NIGHTLY`` is set to ``1`` | |
| the cookbooks will be run against the latest development version of | |
| Arrow published by the `Nightly jobs. <https://arrow.apache.org/docs/python/install.html#installing-nightly-packages>`_ | |
| Example to run the cookbooks using the nightly jobs: | |
| ``` | |
| $ ARROW_NIGHTLY=1 | |
| $ make pytest | |
| ``` | |
| Adding Python Recipes | |
| ===================== | |
| The recipes are written in **reStructuredText** format using | |
| the `Sphinx <https://www.sphinx-doc.org/>`_ documentation system. | |
| New recipes can be added to one of the existing ``.rst`` files if | |
| they suit that section or you can create new sections by adding | |
| additional ``.rst`` files in the ``source`` directory. You just | |
| need to remember to add them to the ``index.rst`` file in the | |
| ``toctree`` for them to become visible. | |
| The only requirement for recipes is that each code block in the recipe | |
| must be written using the ``.. testcode::`` directive, | |
| so that it can get tested. | |
| If the code block changes, alters or creates data, the recipe should | |
| ``print`` the data to show how it changed and have a ``.. testoutput::`` | |
| directive to confirm that the printed data is the expected one. | |
| For example a new recipe about how to create an Arrow array | |
| might look like: | |
| .. code-block:: | |
| You can create a new :class:`pyarrow.Array` providing the | |
| data for the array through the :meth:`pyarrow.array` factory function | |
| .. testcode:: | |
| import pyarrow as pa | |
| array = pa.array(range(5)) | |
| print(array) | |
| .. testoutput:: | |
| [ | |
| 0, | |
| 1, | |
| 2, | |
| 3, | |
| 4 | |
| ] | |
| If you refer to any ``pyarrow`` class, function or method using | |
| ``:class:``, ``:meth:`` or ``:func:`` directives a link to their | |
| documentation in the pyarrow API reference will be automatically | |
| created. | |
| ------------------------------------------------------------------------ | |
| All participation in the Apache Arrow project is governed by the Apache | |
| Software Foundation’s | |
| `code of conduct <https://www.apache.org/foundation/policies/conduct.html>`_. |