amol- commented on a change in pull request #1: URL: https://github.com/apache/arrow-cookbook/pull/1#discussion_r673818941
########## File path: python/CONTRIBUTING.rst ########## @@ -0,0 +1,68 @@ +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 suite 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 ``.. 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 + ] Review comment: At the time the cookbook was started there has been some discussion about using ipython or doctest directives, but I felt that the doctest directive is a bit more convenient for a few reasons 1) It tends to decouple "building the docs" and "testing the docs". Those are two clearly separated concerns and commands. When building the doctest directives are in no way different from a standard `code-block`. They don't introduce any slow down, nor need the code to actually work. This allows a faster development cycle where the author of the documentation can write the docs and immediately see the formatting/output and separatedly focus on the actual codeblocks verification 2) While ipython does support output verification using the `@doctest` directive decorator, it seem a bit of an afterthought. The doctest directive seems to have been designed from the begin with the goal of output verification and thus has better handling for "wildcard output", blanklines, etc... 3) The fact that it decouples testing and building doesn't cause the slowdown described in https://issues.apache.org/jira/browse/ARROW-13159 when building the documentation. -- 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]
