westonpace commented on a change in pull request #22: URL: https://github.com/apache/arrow-cookbook/pull/22#discussion_r691741515
########## File path: cpp/CONTRIBUTING.md ########## @@ -0,0 +1,184 @@ +Bulding the C++ Cookbook +======================== + +The C++ cookbook combines output from a set of C++ test programs with +an RST document tree rendered with sphinx. + +Running ``make py`` from the cookbook root directory (the one where +the ``README.rst`` exists) will install all necessary dependencies, +run the tests to generate the output, and will compile the cookbook +to HTML. + +You will see the compiled result inside the ``build/cpp`` directory. + +The above process requires conda to be installed and is primarily +intended for build systems. See below for more information on setting +up a development environment for developing recipes. + +Developing C++ Recipes +====================== + +Every recipe is a combination of prose written in **reStructuredText** +format using the `Sphinx <https://www.sphinx-doc.org/>`_ documentation +system and a snippet of a googletest test. + +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. + +Referencing a C++ Snippet +------------------------- + +Most recipes will reference a snippet of C++ code. For simplicity +a custom `recipe` directive htat can be used like so: + +``` +.. recipe:: ../code/creating_arrow_objects.cc CreatingArrays + :caption: Creating an array from C++ primitives + :dedent: 4 +``` + +Each `recipe` directive has two requried arguments. The first is +a path to the file containing the source file containing the snippet +and the second is the name of the snippet and must correspond to a +set of CreateRecipe/EndRecipe calls in the source file. + +The directive will generate two code blocks in the cookbook. The first +code block will contain the source code itself and will be annotated +with any (optional) caption specified on the recipe directive. The +second block will contain the test output. + +The optional `dedent` argument should be used to remove leading white +space from your source code. + +Writing a C++ Snippet +--------------------- + +Each snippet source file contains a set of +[googletest](https://github.com/google/googletest) tests. Feel free to +use any googletest features needed to help setup and verify your test. +To reference a snippet you need to surround it in `BeginRecipe` and +`EndRecipe` calls. For example: + +``` +StartRecipe("CreatingArrays"); +arrow::Int32Builder builder; +ASSERT_OK(builder.Append(1)); Review comment: #44 -- 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]
