| .. 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>`_. |