ianmcook commented on a change in pull request #1: URL: https://github.com/apache/arrow-cookbook/pull/1#discussion_r674919096
########## File path: python/CONTRIBUTING.rst ########## @@ -0,0 +1,69 @@ +Bulding the Python Cookbook +=========================== + +The python cookbook is based on 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. + +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. Review comment: ```suggestion 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>`_. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
